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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 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 Thu Oct 2 10:12:22 2008 *************** *** 1,91 **** - - -
Administration Reference
-
-
-
CellServDB (server version)
-Lists the local cell's database server machines -
Description -
The server version of the 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 kaserver, buserver, - ptserver, and vlserver) processes, which maintain the - cell's administrative AFS databases. The initial version of the - file is created with the 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 /usr/afs/etc directory - on each AFS server machine. -
The database server processes consult the 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 CellServDB file is in ASCII format, do not use a - text editor to alter it. Instead always use the appropriate commands - from the bos command suite: -
-
-
- The bos addhost command to add a machine to the file -
- The bos listhosts command to display the list of machines from - the file -
- The bos removehost command to remove a machine from the file -
In cells that run the United States edition of AFS and use the Update - Server to distribute the contents of the /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. For instructions on adding - and removing database server machine, see the IBM AFS Quick - Beginnings chapter on installing additional server machines. -
The server version of the CellServDB file is distinct from the - client version, which resides in the /usr/vice/etc directory on - each AFS client machine. The server version lists only the local - cell's database server machines, whereas 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. -
Related Information -
buserver -
kaserver -
ptserver -
vlserver -
upclient -
upserver -
IBM AFS Quick Beginnings -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf021.htm diff -c openafs/doc/html/AdminReference/auarf021.htm:1.1 openafs/doc/html/AdminReference/auarf021.htm:removed *** openafs/doc/html/AdminReference/auarf021.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf021.htm Thu Oct 2 10:12:22 2008 *************** *** 1,57 **** - - -
Administration Reference
-
-
-
FileLog
-Traces File Server operations -
Description -
The FileLog file records a trace of File Server - (fileserver process) operations on the local machine and describes - any error conditions it encounters. -
If the FileLog file does not already exist in the - /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 - FileLog.old, overwriting the existing - FileLog.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 file - 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 - FileLog file grant the required 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. -
Related Information -
UserList -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf022.htm diff -c openafs/doc/html/AdminReference/auarf022.htm:1.1 openafs/doc/html/AdminReference/auarf022.htm:removed *** openafs/doc/html/AdminReference/auarf022.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf022.htm Thu Oct 2 10:12:22 2008 *************** *** 1,49 **** - - -
Administration Reference
-
-
-
FORCESALVAGE
-Forces salvage of entire partition -
Description -
The FORCESALVAGE file, if present on an AFS server partition - (that is, in a /vicep directory), signals that the Salvager must - salvage the entire partition. The AFS-modified version of the - 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 - /usr/afs/logs/FileLog file. The Bos Server then invokes the - Salvager to salvage the partition. -
Related Information -
FileLog -
salvager -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf023.htm diff -c openafs/doc/html/AdminReference/auarf023.htm:1.1 openafs/doc/html/AdminReference/auarf023.htm:removed *** openafs/doc/html/AdminReference/auarf023.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf023.htm Thu Oct 2 10:12:22 2008 *************** *** 1,73 **** - - -
Administration Reference
-
-
-
KeyFile
-Defines AFS server encryption keys -
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 /usr/afs/etc directory on every server machine. For more - detailed information on mutual authentication and server encryption keys, see - the 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 KeyFile file must always include a key with - the same key version number and contents as the key currently listed for the - afs entry in the Authentication Database. -
The KeyFile file is in binary format, so always use the - appropriate commands from the bos command suite to administer - it: -
-
-
- The bos addkey command to define a new key -
- The bos listkeys command to display the keys -
- The bos removekey command to remove a key from the file -
In cells that run the United States edition of AFS and use the Update - Server to distribute the contents of the /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. -
Related Information -
upclient -
upserver -
IBM AFS Administration Guide -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf024.htm diff -c openafs/doc/html/AdminReference/auarf024.htm:1.1 openafs/doc/html/AdminReference/auarf024.htm:removed *** openafs/doc/html/AdminReference/auarf024.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf024.htm Thu Oct 2 10:12:22 2008 *************** *** 1,70 **** - - -
Administration Reference
-
-
-
NetInfo (client version)
-Defines client machine interfaces to register with the File Server -
Description -
The NetInfo file lists the IP addresses of one or more of the - local machine's network interfaces. If it exists in the - /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 /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 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 NetRestrict file. To display the addresses - the Cache Manager is currently registering with File Servers, use the fs - getclientaddrs command. To replace the current list of interfaces - with a new one between reboots of the client machine, use the fs - setclientaddrs command. -
Related Information -
NetRestrict (client version) -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf025.htm diff -c openafs/doc/html/AdminReference/auarf025.htm:1.1 openafs/doc/html/AdminReference/auarf025.htm:removed *** openafs/doc/html/AdminReference/auarf025.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf025.htm Thu Oct 2 10:12:22 2008 *************** *** 1,67 **** - - -
Administration Reference
-
-
-
NetInfo (server version)
-Defines interfaces that File Server registers in VLDB and Ubik uses for - database server machines -
Description -
The NetInfo file, if present in the /usr/afs/local - directory, defines the following: -
-
-
- On a file server machine, the local interfaces that the File Server - (fileserver process) can register in the Volume Location Database - (VLDB) at initialization time -
- 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 -
If the 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 /usr/vice/etc/NetRestrict file, if it - exists. The File Server records the resulting list in the - /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 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 vos listaddrs command. -
Related Information -
NetRestrict (server version) -
sysid -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf026.htm diff -c openafs/doc/html/AdminReference/auarf026.htm:1.1 openafs/doc/html/AdminReference/auarf026.htm:removed *** openafs/doc/html/AdminReference/auarf026.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf026.htm Thu Oct 2 10:12:22 2008 *************** *** 1,60 **** - - -
Administration Reference
-
-
-
NetRestrict (client version)
-Defines client interfaces not to register with the File Server -
Description -
The NetRestrict file, if present in a client machine's - /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 the reference page for the client - version of the NetInfo file. -
As it initializes, the Cache Manager constructs a list of interfaces to - register, from the /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 - NetRestrict file, if it exists. The Cache Manager records - the resulting list in kernel memory. -
The 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 255 is a wildcard - that represents all possible addresses in that field. For example, the - value 192.12.105.255 indicates that the Cache - Manager does not register any of the addresses in the - 192.12.105 subnet. -
To display the addresses the Cache Manager is currently registering with - File Servers, use the fs getclientaddrs command. -
Related Information -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf027.htm diff -c openafs/doc/html/AdminReference/auarf027.htm:1.1 openafs/doc/html/AdminReference/auarf027.htm:removed *** openafs/doc/html/AdminReference/auarf027.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf027.htm Thu Oct 2 10:12:22 2008 *************** *** 1,71 **** - - -
Administration Reference
-
-
-
NetRestrict (server version)
-Defines interfaces that File Server does not register in VLDB and Ubik does - not use for database server machines -
Description -
The NetRestrict file, if present in the - /usr/afs/local directory, defines the following: -
-
-
- On a file server machine, the local interfaces that the File Server - (fileserver process) does not register in the Volume Location - Database (VLDB) at initialization time -
- 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 -
As it initializes, the File Server constructs a list of interfaces to - register, from the /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 NetRestrict file, if it exists. The File - Server records the resulting list in the /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 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 255 is a wildcard - that represents all possible addresses in that field. For example, the - value 192.12.105.255 indicates that the Cache - Manager does not register any of the addresses in the - 192.12.105 subnet. -
To display the File Server interface addresses registered in the VLDB, use - the vos listaddrs command. -
Related Information -
sysid -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf028.htm diff -c openafs/doc/html/AdminReference/auarf028.htm:1.1 openafs/doc/html/AdminReference/auarf028.htm:removed *** openafs/doc/html/AdminReference/auarf028.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf028.htm Thu Oct 2 10:12:22 2008 *************** *** 1,67 **** - - -
Administration Reference
-
-
-
NoAuth
-Disables authorization checking -
Description -
The NoAuth file, if present in a server machine's - /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: -
-
-
- During installation of the machine, as instructed in the IBM AFS - Quick Beginnings -
- During correction of a server encryption key emergency, as discussed in - the IBM AFS Administration Guide -
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. -
Create the file in one of the following ways: -
-
-
- By issuing the bosserver initialization command with the - -noauth flag, if the Basic OverSeer (BOS) Server is not already - running -
- By issuing the bos setauth command with off as the - value for the -authrequired argument, if the BOS Server is already - running -
To remove the file, issue the bos setauth command with - on as the value for the -authrequired argument. -
The file's contents, if any, are ignored; an empty (zero-length) - file is effective. -
Related Information -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf029.htm diff -c openafs/doc/html/AdminReference/auarf029.htm:1.1 openafs/doc/html/AdminReference/auarf029.htm:removed *** openafs/doc/html/AdminReference/auarf029.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf029.htm Thu Oct 2 10:12:22 2008 *************** *** 1,58 **** - - -
Administration Reference
-
-
-
SALVAGE.fs
-Triggers salvaging of AFS server partitions -
Description -
The SALVAGE.fs file, if present in a file server - machine's /usr/afs/local directory, indicates to the Basic - OverSeer (BOS) Server (bosserver process) that it must invoke the - Salvager (salvager process) during recovery from a failure of the - File Server (fileserver process). -
The BOS Server creates the zero-length file each time it starts or restarts - the fs process. When the File Server exits normally (for - example, in response to the bos shutdown or bos stop - command), the BOS Server removes the file. However, if the File Server - exits unexpectedly, the file remains in the /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 bos salvage command or log onto the file server - machine as the local superuser root and issue the - salvager command. -
Related Information -
salvager -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf030.htm diff -c openafs/doc/html/AdminReference/auarf030.htm:1.1 openafs/doc/html/AdminReference/auarf030.htm:removed *** openafs/doc/html/AdminReference/auarf030.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf030.htm Thu Oct 2 10:12:22 2008 *************** *** 1,57 **** - - -
Administration Reference
-
-
-
SalvageLog
-Traces Salvager operations -
Description -
The SalvageLog file records a trace of Salvager - (salvager process) operations on the local machine and describes - any error conditions it encounters. -
If the SalvageLog file does not already exist in the - /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 SalvageLog.old, - overwriting the existing SalvageLog.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 file - 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 - SalvageLog file grant the required 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. -
Related Information -
UserList -
salvager -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf031.htm diff -c openafs/doc/html/AdminReference/auarf031.htm:1.1 openafs/doc/html/AdminReference/auarf031.htm:removed *** openafs/doc/html/AdminReference/auarf031.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf031.htm Thu Oct 2 10:12:22 2008 *************** *** 1,59 **** - - -
Administration Reference
-
-
-
TE_device_name
-Purpose -
Logs error messages from the Tape Coordinator process -
Description -
The TE_device_name file logs error messages generated - by the Backup System Tape Coordinator (butc process) that controls - the tape device or backup data file indicated by device_name. -
As the Tape Coordinator initializes, it creates the file in ASCII format in - the /usr/afs/backup directory. If there is an existing file, - the Tape Coordinator renames it to - TE_device_name.old, overwriting the - existing TE_device_name.old file if it - exists. -
For a tape device, the Tape Coordinator derives the variable - device_name portion of the filename from the device pathname listed - in the local /usr/afs/backup/tapeconfig file, by stripping off the - initial /dev/ string and replacing any other slashes in the name - with underscores. For example, the filename for a device called - /dev/rmt/4m is TE_rmt_4m. Similarly, for a backup - data file the Tape Coordinator strips off the initial slash (/) and replaces - any other slashes in the name with underscores. For example, the - filename for a backup data file called /var/tmp/FILE is - 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 /usr/afs/backup/TL_device_name - file, which traces most of the Tape Coordinator's actions. -
Related Information -
butc -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf032.htm diff -c openafs/doc/html/AdminReference/auarf032.htm:1.1 openafs/doc/html/AdminReference/auarf032.htm:removed *** openafs/doc/html/AdminReference/auarf032.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf032.htm Thu Oct 2 10:12:22 2008 *************** *** 1,79 **** - - -
Administration Reference
-
-
-
ThisCell (client version)
-Defines client machine's cell membership -
Description -
The client version of the ThisCell file defines the complete - Internet domain-style name (for example, abc.com) of the - cell to which the local client machine belongs. It must reside in the - /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 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: -
-
-
- The cell in which the machine's users authenticate by default.
- The effect is two-fold:
-
-
-
- The AFS-modified login utilities and the klog command - interpreter contact an Authentication Server in the cell named in the - ThisCell file (unless -cell argument to the - klog command specifies an alternate cell). -
- 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. -
- 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 fs getcellstatus and fs setcell - reference pages. -
- Which AFS server processes the local AFS command interpreters contact by - default as they execute commands issued on the machine. -
The client version of the ThisCell file is distinct from the - server version, which resides in the /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. -
Related Information -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf033.htm diff -c openafs/doc/html/AdminReference/auarf033.htm:1.1 openafs/doc/html/AdminReference/auarf033.htm:removed *** openafs/doc/html/AdminReference/auarf033.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf033.htm Thu Oct 2 10:12:22 2008 *************** *** 1,61 **** - - -
Administration Reference
-
-
-
ThisCell (server version)
-Defines server machine's cell membership -
Description -
The server version of the ThisCell file defines the complete - Internet domain-style name (for example, abc.com) of the - cell to which the server machine belongs. It must reside in the - /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 bos - setcellname command during the installation of the cell's first - file server machine, and the 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. -
The server version of the ThisCell file is distinct from the - client version, which resides in the /usr/vice/etc directory on - each AFS client 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. -
Related Information -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf034.htm diff -c openafs/doc/html/AdminReference/auarf034.htm:1.1 openafs/doc/html/AdminReference/auarf034.htm:removed *** openafs/doc/html/AdminReference/auarf034.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf034.htm Thu Oct 2 10:12:22 2008 *************** *** 1,55 **** - - -
Administration Reference
-
-
-
TL_device_name
-Purpose -
Traces Tape Coordinator operations and logs errors -
Description -
The TL_device_name file logs the actions performed by - the Backup System Tape Coordinator (butc process) that controls the - tape device or backup data file indicated by device_name. It - also records the same error and warning messages written to the - TE_device_name file. -
As the Tape Coordinator initializes, it creates the file in ASCII format in - the /usr/afs/backup directory. If there is an existing file, - the Tape Coordinator renames it to - TL_device_name.old, overwriting the - existing TL_device_name.old file if it - exists. -
For a tape device, the Tape Coordinator derives the variable - device_name portion of the filename from the device pathname listed - in the local /usr/afs/backup/tapeconfig file, by stripping off the - initial /dev/ string and replacing any other slashes in the name - with underscores. For example, the filename for a device called - /dev/rmt/4m is TL_rmt_4m. Similarly, for a backup - data file the Tape Coordinator strips off the initial slash (/) and replaces - any other slashes in the name with underscores. For example, the - filename for a backup data file called /var/tmp/FILE is - TL_var_tmp_FILE. -
Related Information -
butc -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf035.htm diff -c openafs/doc/html/AdminReference/auarf035.htm:1.1 openafs/doc/html/AdminReference/auarf035.htm:removed *** openafs/doc/html/AdminReference/auarf035.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf035.htm Thu Oct 2 10:12:22 2008 *************** *** 1,59 **** - - -
Administration Reference
-
-
-
UserList
-Defines privileged administrators -
Description -
The UserList file lists the AFS usernames of the system - administrators authorized to issue privileged bos, vos, - and backup commands that affect the local server machine or the - volumes housed on it. It must reside in the /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 bos command suite: -
-
-
- The bos adduser command to add a user to the file -
- The bos listusers command to display the contents of the file -
- The bos removeuser command to remove a user from the file -
Although it is theoretically possible to list different administrators in - the 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 /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. -
Related Information -
upclient -
upserver -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf036.htm diff -c openafs/doc/html/AdminReference/auarf036.htm:1.1 openafs/doc/html/AdminReference/auarf036.htm:removed *** openafs/doc/html/AdminReference/auarf036.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf036.htm Thu Oct 2 10:12:22 2008 *************** *** 1,94 **** - - -
Administration Reference
-
-
-
Vn
-Houses a chunk of AFS data in the disk cache -
Description -
A Vn 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 Vn files equal to the largest of the following: -
-
-
- 100 -
- One and a half times the result of dividing the cache size by the chunk - size (cachesize/chunksize * 1.5) -
- The result of dividing the cache size by 10 MB (10,240) -
The Cache Manager determines the cache size from the -blocks - argument to the afsd command, or if the argument is not included, - from the third field of the /usr/vice/etc/cacheinfo file. - The default chunk size is 64 KB; use the -chunksize argument - to the afsd command to override it. To override the default - number of chunks resulting from the calculation, include the -files - argument to the afsd command. The afsd reference - page describes the restrictions on acceptable values for each of the - arguments. -
If the disk cache directory houses fewer Vn files than - necessary, the Cache Manager creates new ones, assigning each a unique integer - n that distinguishes it from the other files; the integers start - with 1 and increment by one for each Vn file - created. The Cache Manager removes files if there are more than - necessary. The Cache Manager also adds and removes - Vn files in response to the fs setcachesize - command, which can be used to alter the cache size between reboots. -
The standard disk cache directory name is /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 /usr/vice/etc/cacheinfo file before issuing the - afsd command, or include the -cachedir argument to the - afsd command. -
Vn files expand and contract to accommodate the size of - the AFS directory listing or file they temporarily house. As mentioned, - by default each Vn file holds up to 64 KB (65,536 bytes) - of a cached AFS element. AFS elements larger than 64 KB are divided - among multiple Vn files. If an element is smaller - than 64 KB, the Vn file expands only to the required - size. A Vn file accommodates only a single element, - so if there many small cached elements, it is possible to exhaust the - available Vn files without reaching the maximum cache - size. -
Cautions -
Editing or removing a Vn file can cause a kernel - panic. To alter cache size (and thus the number of - Vn files) between reboots, use the fs - setcachesize command. Alternatively, alter the value of the - -blocks, -files or -chunksize arguments to - the afsd command invoked in the machine's AFS initialization - file, and reboot. To refresh the contents of one or more - Vn files, use the fs flush or fs - flushvolume command. If a Vn file is - accidentally modified or deleted, rebooting the machine usually restores - normal performance. -
Related Information -
afsd -
fs flush -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf037.htm diff -c openafs/doc/html/AdminReference/auarf037.htm:1.1 openafs/doc/html/AdminReference/auarf037.htm:removed *** openafs/doc/html/AdminReference/auarf037.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf037.htm Thu Oct 2 10:12:22 2008 *************** *** 1,46 **** - - -
Administration Reference
-
-
-
Vvol_ID.vol
-Represents an AFS volume -
Description -
The Vvol_ID.vol file is the header - file for the AFS volume with volume ID vol_ID. There is one - such file for each volume stored on an AFS server (/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 vos listvol or 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 - Manager. -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf038.htm diff -c openafs/doc/html/AdminReference/auarf038.htm:1.1 openafs/doc/html/AdminReference/auarf038.htm:removed *** openafs/doc/html/AdminReference/auarf038.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf038.htm Thu Oct 2 10:12:22 2008 *************** *** 1,75 **** - - -
Administration Reference
-
-
-
VLLog
-Traces Volume Location Server operations -
Description -
The VLLog file records a trace of Volume Location (VL) Server - (vlserver process) operations on the local machine and describes - any error conditions it encounters. -
If the VLLog file does not already exist in the - /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 VLLog.old, - overwriting the existing VLLog.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 - VLLog file grant the required 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. -
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 root. -
# kill -TSTP vlserver_pid - --
where vlserver_pid is the process ID of the vlserver - process, as reported in the output from the standard UNIX ps - command. To increase to the second and third levels of detail, repeat - the command. -
To disable logging, issue the following command. -
- # kill -HUP vlserver_pid - --
To decrease the level of logging, first completely disable it and then - issue the kill -TSTP command as many times as necessary to reach - the desired level. -
Related Information -
UserList -
vlserver -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf039.htm diff -c openafs/doc/html/AdminReference/auarf039.htm:1.1 openafs/doc/html/AdminReference/auarf039.htm:removed *** openafs/doc/html/AdminReference/auarf039.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf039.htm Thu Oct 2 10:12:22 2008 *************** *** 1,57 **** - - -
Administration Reference
-
-
-
VolserLog
-Traces Volume Server operations -
Description -
The VolserLog file records a trace of Volume Server - (volserver process) operations on the local machine and describes - any error conditions it encounters. -
If the VolserLog file does not already exist in the - /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 - VolserLog.old, overwriting the existing - VolserLog.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 file - 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 - VolserLog file grant the required 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 - problems. -
Related Information -
UserList -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf040.htm diff -c openafs/doc/html/AdminReference/auarf040.htm:1.1 openafs/doc/html/AdminReference/auarf040.htm:removed *** openafs/doc/html/AdminReference/auarf040.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf040.htm Thu Oct 2 10:12:22 2008 *************** *** 1,56 **** - - -
Administration Reference
-
-
-
VolumeItems
-Records location mappings for volumes accessed by a Cache Manager using a - disk cache -
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 pwd command. -
As it initializes, the Cache Manager creates the binary-format - VolumeItems file in the local disk cache directory, and it must - always remain there. The conventional directory name is - /usr/vice/cache. -
Cautions -
Editing or removing the VolumeItems file can cause a kernel - panic. To refresh the contents of the file, instead use the fs - checkvolumes command. If the VolumeItems file is - accidentally modified or deleted, rebooting the machine usually restores - normal performance. -
Related Information -
afsd -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf041.htm diff -c openafs/doc/html/AdminReference/auarf041.htm:1.1 openafs/doc/html/AdminReference/auarf041.htm:removed *** openafs/doc/html/AdminReference/auarf041.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf041.htm Thu Oct 2 10:12:22 2008 *************** *** 1,43 **** - - -
Administration Reference
-
-
-
afszcm.cat
-Error message catalog for debugging the Cache Manager -
Description -
The afszcm.cat file is a message catalog for the Cache - Manager. The 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 - 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. -
Related Information -
afsd -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf042.htm diff -c openafs/doc/html/AdminReference/auarf042.htm:1.1 openafs/doc/html/AdminReference/auarf042.htm:removed *** openafs/doc/html/AdminReference/auarf042.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf042.htm Thu Oct 2 10:12:22 2008 *************** *** 1,59 **** - - -
Administration Reference
-
-
-
bdb.DB0 and bdb.DBSYS1
-Contain the Backup Database and associated log -
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 (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 - 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 - bdb.DB0 file on tape on a regular basis, using the UNIX - tar command or another local disk backup utility. -
Related Information -
backup -
buserver -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf043.htm diff -c openafs/doc/html/AdminReference/auarf043.htm:1.1 openafs/doc/html/AdminReference/auarf043.htm:removed *** openafs/doc/html/AdminReference/auarf043.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf043.htm Thu Oct 2 10:12:22 2008 *************** *** 1,79 **** - - -
Administration Reference
-
-
-
cacheinfo
-Purpose -
Defines configuration parameters for the Cache Manager -
Description -
The 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 - /usr/vice/etc directory. Use a text editor to create it - during initial configuration of the client machine; the required format - is as follows: -
mount_dir:cache_dir:cache_size - --
where -
-
-
- mount_dir -
- Names the local disk directory at which the Cache Manager mounts the AFS - namespace. It must exist before the afsd program - runs. The conventional value is /afs. Using any other - value prevents traversal of pathnames that begin with /afs (such as - pathnames to files in foreign cells that do use the conventional name). - The -mountdir argument to the afsd command overrides - this value. -
- cache_dir -
- Names the local disk directory to use as a cache. It must exist - before the afsd program runs. The standard value is - /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 -cachedir argument to the afsd command - overrides this value. -
- 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 -blocks argument to the afsd command overrides - this value. To reset cache size without rebooting on a machine that - uses disk caching, use the fs setcachesize command. To - display the current size of a disk or memory cache between reboots, use the - fs getcacheparms command. -
Examples -
The following example cacheinfo file mounts the AFS namespace at - /afs, establishes a disk cache in the /usr/vice/cache - directory, and defines cache size as 50,000 1-kilobyte blocks. -
/afs:/usr/vice/cache:50000 - --
Related Information -
afsd -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf044.htm diff -c openafs/doc/html/AdminReference/auarf044.htm:1.1 openafs/doc/html/AdminReference/auarf044.htm:removed *** openafs/doc/html/AdminReference/auarf044.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf044.htm Thu Oct 2 10:12:22 2008 *************** *** 1,82 **** - - -
Administration Reference
-
-
-
fms.log
-Purpose -
Records output from the fms command -
Description -
The fms.log file records the output generated by the - fms command. The output includes two numbers that can appear - in a tape device's entry in the /usr/afs/backup/tapeconfig - file on the Tape Coordinator machine to which the tape device is - attached: -
-
-
- The capacity in bytes of the tape in the device -
- The size in bytes of the end-of-file (EOF) marks (often referred to simply - as filemarks) that the tape device writes -
When transferring the numbers recorded in this file to the - tapeconfig file, adjust them as specified on the reference page for - the 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 fms command interpreter creates it. - In this case, the directory's mode bits must grant the 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 - w permission to the issuer of the fms command. - The 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 cat command. By default, the mode bits on the - fms.log file grant the required r permission only - to the owner (which is the local superuser root by default). -
Output -
The first few lines of the file provide a simple trace of the - 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 tape_size bytes - File marks are filemark_size bytes - --
Examples -
The following example of the fms.log file specifies that - the tape used during the execution of the 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 - Tape capacity is 2136604672 bytes - File marks are 1910220 bytes - --
Related Information -
fms -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf045.htm diff -c openafs/doc/html/AdminReference/auarf045.htm:1.1 openafs/doc/html/AdminReference/auarf045.htm:removed *** openafs/doc/html/AdminReference/auarf045.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf045.htm Thu Oct 2 10:12:22 2008 *************** *** 1,60 **** - - -
Administration Reference
-
-
-
kaserver.DB0 and kaserver.DBSYS1
-Contain the Authentication Database and associated log -
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 (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 tar - command. -
Related Information -
kas -
kaserver -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf046.htm diff -c openafs/doc/html/AdminReference/auarf046.htm:1.1 openafs/doc/html/AdminReference/auarf046.htm:removed *** openafs/doc/html/AdminReference/auarf046.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf046.htm Thu Oct 2 10:12:22 2008 *************** *** 1,55 **** - - -
Administration Reference
-
-
-
kaserverauxdb
-Records failed authentication attempts -
Description -
The file kaserverauxdb records failed authentication attempts - for the local Authentication Server. The server creates it - automatically in the /usr/afs/local directory by default; use - the -localfiles argument to the 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 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 kas - examine command reports an account's maximum number of failed - attempts, the lockout time, and whether the account is currently - locked. -
Related Information -
kaserver.DB0 and kaserver.DBSYS1 -
kaserver -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf047.htm diff -c openafs/doc/html/AdminReference/auarf047.htm:1.1 openafs/doc/html/AdminReference/auarf047.htm:removed *** openafs/doc/html/AdminReference/auarf047.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf047.htm Thu Oct 2 10:12:22 2008 *************** *** 1,60 **** - - -
Administration Reference
-
-
-
prdb.DB0 and prdb.DBSYS1
-Contain the Protection Database and associated log -
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 - (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 tar - command. -
Related Information -
pts -
ptserver -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf048.htm diff -c openafs/doc/html/AdminReference/auarf048.htm:1.1 openafs/doc/html/AdminReference/auarf048.htm:removed *** openafs/doc/html/AdminReference/auarf048.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf048.htm Thu Oct 2 10:12:22 2008 *************** *** 1,40 **** - - -
Administration Reference
-
-
-
salvage.lock
-Purpose -
Prevents multiple simultaneous salvage operations on a partition -
Description -
The salvage.lock file guarantees that only one Salvager - (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 /usr/afs/local directory and invokes the - 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. -
Related Information -
salvager -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf049.htm diff -c openafs/doc/html/AdminReference/auarf049.htm:1.1 openafs/doc/html/AdminReference/auarf049.htm:removed *** openafs/doc/html/AdminReference/auarf049.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf049.htm Thu Oct 2 10:12:22 2008 *************** *** 1,66 **** - - -
Administration Reference
-
-
-
sysid
-Lists file server machine interface addresses registered in VLDB -
Description -
The sysid file records the network interface addresses that the - File Server (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 /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 - /usr/afs/local/NetRestrict file, if it exists. The File - Server records the resulting list in the binary-format 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. -
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 /usr/afs/local directory - from an existing file server machine to a newly installed one, be sure to - remove the sysid file from the new machine before starting the - fs trio of processes, which includes the fileserver - process. -
Some versions of AFS limit how many of a file server machine's - interface addresses that can be registered. Consult the IBM AFS - Release Notes. -
Related Information -
NetRestrict (server version) -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf050.htm diff -c openafs/doc/html/AdminReference/auarf050.htm:1.1 openafs/doc/html/AdminReference/auarf050.htm:removed *** openafs/doc/html/AdminReference/auarf050.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf050.htm Thu Oct 2 10:12:22 2008 *************** *** 1,165 **** - - -
Administration Reference
-
-
-
tapeconfig
-Defines configuration parameters for all tape devices and backup data files - on a Tape Coordinator machine -
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 /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: -
[capacity filemark_size] device_name port_offset - --
where -
-
-
- 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:
-
-
-
- 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 backup dump or backup - savedb operation. If there is already a capacity value on the - label, the Tape Coordinator uses it instead. -
- When the -size argument is omitted the first time the - backup labeltape command is used on a given tape or file. - The Tape Coordinator copies this value into the label's capacity - field. -
-
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 IBM AFS - Administration Guide chapter on configuring the Backup System. If - using a value obtained from the 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 - 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. -
-
-
-
- kor K for kilobytes (KB) -
- m or M for megabytes (MB) -
- g or G for gigabytes (GB) -
- t or T for terabytes (TB) -
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 - filemark_size field empty, or provide a value in both of them. -
- 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.
-
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 IBM AFS Administration Guide chapter on - configuring the Backup System. If using a value obtained from the - 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. -
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 capacity field - empty, or provide a value in both of them. -
- 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 - /dev/. For a backup data file, this field defines the - complete pathname; for a discussion of suggested naming conventions see - the description of the FILE instruction in CFG_device_name. -
- 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 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 - tapeconfig file. Assign port offset 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 - -portoffset argument from the largest possible number of - backup commands. -
Privilege Required -
Creating the file requires UNIX w (write) and - x (execute) permissions on the - /usr/afs/backup directory. Editing the file requires UNIX - w (write) permission on the file. -
Examples -
The following example tapeconfig file configures three tape - devices and a backup data file. The first device has device name - /dev/rmt/0h, and is assigned port offset 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 /dev/rmt/3h drive has half the capacity but a much - smaller filemark size; its port offset is 3. The third - device listed, /dev/rmt/4h, has the same capacity and filemark size - as the first device and is assigned port offset 2. Port - offset 4 is assigned to the backup data file /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 - 2G 1m /dev/rmt/4h 2 - 1.5G 0 /dev/FILE 4 - --
Related Information -
butc -
fms -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf051.htm diff -c openafs/doc/html/AdminReference/auarf051.htm:1.1 openafs/doc/html/AdminReference/auarf051.htm:removed *** openafs/doc/html/AdminReference/auarf051.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf051.htm Thu Oct 2 10:12:22 2008 *************** *** 1,58 **** - - -
Administration Reference
-
-
-
vldb.DB0 and vldb.DBSYS1
-Contain the Volume Location Database and associated log -
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 - (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. -
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. -
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 tar command. -
Related Information -
vlserver -
vos -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf052.htm diff -c openafs/doc/html/AdminReference/auarf052.htm:1.3 openafs/doc/html/AdminReference/auarf052.htm:removed *** openafs/doc/html/AdminReference/auarf052.htm:1.3 Thu Jul 29 00:17:02 2004 --- openafs/doc/html/AdminReference/auarf052.htm Thu Oct 2 10:12:22 2008 *************** *** 1,122 **** - - -
Administration Reference
-
-
-
afsmonitor Configuration File
-Provides instructions for the afsmonitor command -
Description -
The afsmonitor configuration file determines which machines the - afsmonitor command probes for File Server or Cache Manager - statistics and which statistics it gathers. Use the -config - argument to the afsmonitor command to identify the configuration - file to use. -
The instructions that can appear in the configuration file are as - follows: -
-
-
- cm host_name -
- Names a client machine for which to display Cache Manager - statistics. The order of cm lines in the file determines the - order in which client machines appear from top to bottom on the System - Overview and Cache Managers output screens. -
- fs host_name -
- Names a file server machine for which to display File Server - statistics. The order of fs lines in the file determines the - order in which file server machines appear from top to bottom on the - System Overview and File Servers output screens. -
- thresh fs | cm field_name thresh_val - [cmd_to_run] [arg1] . . . - [argn] -
- Assigns the threshold value thresh_val to the statistic
- field_name, for either a File Server statistic (fs) or a
- Cache Manager statistic (cm). The optional
- cmd_to_execute field names a binary or script to execute each time
- the value of the statistic changes from being below thresh_val to
- being at or above thresh_val. A change between two values that
- both exceed thresh_val does not retrigger the binary or
- script. The optional arg1 through
- argn fields are additional values that the
- afsmonitor program passes as arguments to the
- cmd_to_execute command. If any of them include one or more
- spaces, enclose the entire field in double quotes.
-
The afsmonitor program passes the following parameters to the - cmd_to_execute: -
- host_name fs|cm field_name
- threshold_val
- actual_val [<arg1>]
- . . . [<argn>]
-
The parameters fs, cm, field_name, - threshold_val, and arg1 through - argn correspond to the values with the same name on the - thresh line. The host_name parameter identifies the - file server or client machine where the statistic has crossed the threshold, - and the actual_val parameter is the actual value of - field_name that exceeds the threshold value. -
Use the thresh line to set either a global threshold, which - applies to all file server machines listed on fs lines or client - machines listed on cm lines in the configuration file, or a - machine-specific threshold, which applies to only one file server or client - machine. -
-
-
- To set a global threshold, place the thresh line before any of - the fs or cm lines in the file. -
- To set a machine-specific threshold, place the thresh line - below the corresponding fs or cm line, and above any - other fs or cm lines. A machine-specific - threshold value always overrides the corresponding global threshold, if - set. Do not place a thresh fs line directly after a - cm line or a thresh cm line directly after a - fs line. -
- show fs | cm field/group/section -
- Specifies which individual statistic, group of statistics, or section of
- statistics to display on the File Servers screen (fs) or
- Cache Managers screen (cm) and the order in which to
- display them. The appendix of afsmonitor statistics in the
- IBM AFS Administration Guide specifies the group and section to
- which each statistic belongs. Include as many 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 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 show fs lines, the - File Servers screen displays all file server statistics, and if - there are no show cm lines, the Cache Managers screen - displays all client statistics. -
- # comments -
- Precedes a line of text that the afsmonitor program ignores - because of the initial number (#) sign, which must appear in the - very first column of the line. -
For a list of the values that can appear in the - field/group/section field of a show instruction, see the - afsmonitor statistics appendix to the IBM AFS Administration - Guide. -
Related Information -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf053.htm diff -c openafs/doc/html/AdminReference/auarf053.htm:1.1 openafs/doc/html/AdminReference/auarf053.htm:removed *** openafs/doc/html/AdminReference/auarf053.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf053.htm Thu Oct 2 10:12:22 2008 *************** *** 1,655 **** - - -
Administration Reference
-
-
-
package Configuration File
-Provides instructions for the package command -
Description -
The package configuration file defines the file system elements - that the package command creates or alters on the local disk of an - AFS client machine it is configuring. Use the -config or - -fullconfig argument to the package command to identify - the configuration file to use. -
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. -
-
-
- B -
- Defines a block special device, such as a disk, which deals with input in - units of multi-byte command blocks -
- C -
- Defines a character special device, such as a terminal or tty, which deals - with input in single character units -
- D -
- Creates a directory -
- F -
- Creates or alters a file to match the contents of a specified source file -
- L -
- Creates a symbolic link -
- S -
- Defines a socket, which is a communications device for UDP and TCP/IP - connections -
- %define -
- Defines a variable or declares a string as defined -
- %ifdef -
- Specifies an action to perform if a certain string is declared or defined -
- %ifndef -
- Specifies an action to perform if a certain string is not declared or - defined -
- %include -
- Includes a library file -
- %undef -
- Declares a string not to be defined, or a variable no longer to have a - value -
The B and C Instructions for Defining Block and Character Special - Devices - - - - - - - - - - - - - - - -
The 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 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_name major_device minor_device owner group mode_bits
-
-
- where -
-
-
- B -
- Indicates the definition of a block special device. It must be a - capital letter. -
- C -
- Indicates the definition of character special device. It must be a - capital letter. -
- device_name -
- 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. -
- major_device -
- 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. -
- minor_device -
- Specifies the device's minor device number in one of hexadecimal, - octal, or decimal format. Precede a hexadecimal number with the string - 0x (zero and the letter x) or an octal number with a - 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. -
- 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 ls -l - command. -
- 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 ls - -lg command. -
- mode_bits -
- Defines the device's UNIX mode bits. Acceptable values are the - standard three- or four-digit numbers corresponding to combinations of - permissions. Examples: 755 corresponds to - rwxr-xr-x, and 644 to rw-r--r--. -
The D Instruction for Creating a Directory - - - - - - - -
The 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[update_code] directory owner group mode_bits - --
where -
-
-
- D -
- Indicates the creation of a directory. It must be a capital - letter. -
- update_code -
- Modulates the directory creation instruction. It is optional and
- follows the letter D directly, without an intervening space.
- Choose one of the two acceptable values:
-
-
-
- X -
- Indicates that the directory is a lost+found directory (used by - the fsck program). -
- R -
- Removes any subdirectory (along its contents) or file that exists in the - existing directory on the local disk but for which an instruction does not - appear in the configuration file. -
- directory -
- Specifies the full pathname of the directory to create. -
- 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 ls -ld - command. -
- 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 ls -lgd - command. -
- mode_bits -
- Defines the directory's UNIX mode bits. Acceptable values are - the standard three- or four-digit numbers corresponding to combinations of - permissions. Examples: 755 corresponds to - drwxr-xr-x, and 644 to drw-r--r--. -
The F Instruction for Creating or Updating a File - - - - - - - -
The 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 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 - I update code is used to prevent that. To add a - .old extension to the current version of the file, include - the O update code. To have the machine reboot automatically - after the package program completes, include the 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 - removed as necessary). -
The instruction has the following syntax: -
F[update_code] file source_file [owner group mode_bits] - --
where -
-
-
- F -
- Indicates the creation or update of a file. It must be a capital - letter. -
- update_code -
- Modulates the file creation instruction. It is optional and follows
- the letter F directly, without an intervening space. Choose
- one or more of the four acceptable values, and list them in any order:
-
-
-
- A -
- Indicates that the pathname in the source_file field is the - complete pathname of the source file, including the filename. If this - argument is omitted, the package command appends the pathname in - the file field to the pathname in the source_file field to - derive the source file's full name. This code allows the source - and target filenames to differ. -
- I -
- Preserves the existing file called file, rather than overwriting - it. -
- O -
- Saves the existing version of the file by appending a - .old extension to it. -
- Q -
- Causes the package command to exit with status code - 4 if it overwrites the file. If the standard - package-related changes have been made to the machine's AFS - initialization file, then status code 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--/vmunix or equivalent--has changed). -
- file -
- Specifies the complete pathname on the local disk of the file to create or - update, including the filename as the final element. -
- source_file -
- 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 package command derives - the source file's full name by appending the file pathname to - this pathname. For example, if the A update code is not - included and the file /afs/abc.com/rs_aix42/bin/grep is the - source file for the /bin/grep binary, the proper value in this - field is /afs/abc.com/rs_aix42. -
- 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 ls -l
- command.
-
To copy the source file's owner to the target file, leave this field - empty. In this case, the group and mode_bits fields - must also be empty. -
- 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 ls -lg
- command.
-
To copy the source file's group to the target file, leave this field - empty. In this case, the owner and mode_bits fields - must also be empty. -
- mode_bits -
- Defines the file's UNIX mode bits. Acceptable values are the
- standard three- or four-digit numbers corresponding to combinations of
- permissions. Examples: 755 corresponds to
- rwxr-xr-x, and 644 to rw-r--r--.
-
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. -
The L Instruction for Creating a Symbolic Link - - - - - - - -
The 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 - 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 - package command replaces it with a symbolic link. -
The instruction has the following syntax: -
L[update_code] link actual_path [owner group mode_bits] - --
where -
-
-
- L -
- Indicates the creation of a symbolic link. It must be a capital - letter. -
- update_code -
- Modulates the link creation instruction. It is optional and follows
- the letter L directly, without an intervening space. Choose
- one or both of the acceptable values, and list them in any order:
-
-
-
- A -
- Indicates that the pathname in the 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 package command - appends the value in the link field to the pathname in the - 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. -
- I -
- Preserves the existing symbolic link called link, rather than - overwriting it. -
- link -
- Specifies the complete local disk pathname of the symbolic link to - create. -
- actual_path -
- Specifies the pathname (local or AFS) of the directory or file to which
- the link refers. If the A update code is included, specify
- the directory or file's complete pathname. Otherwise, the
- package command derives the actual directory or file's full
- name by appending the value in the link field to this
- pathname. For example, if the A update code is not included
- and /etc/ftpd is a symbolic link to the file
- /afs/abc.com/sun4x_56/etc/ftpd, the proper value in this
- field is /afs/abc.com/sun4x_56.
-
The package command interpreter correctly handles pathnames that - begin with the ./ (period, slash) or - ../ (two periods, slash) notation, interpreting them - relative to the current working directory from which the package - command is invoked. -
- 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 ls -l
- command.
-
To designate the issuer of the package command (usually, the - local superuser root) as the symbolic link's owner, leave this - field empty. In this case, the group and mode_bits - fields must also be empty. -
- 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 ls -lg
- command.
-
To have the symbolic link's group match the default group associated - with the package command's issuer, leave this field - empty. The issuer is usually the local superuser root and - the default group is designated in the issuer's entry in the local - /etc/passwd file or equivalent. If this field is left empty, - the owner and mode_bits fields must also be empty. -
- mode_bits -
- Defines the symbolic link's UNIX mode bits. Acceptable values
- are the standard three- or four-digit numbers corresponding to combinations of
- permissions. Examples: 755 corresponds to
- rwxr-xr-x, and 644 to rw-r--r--.
-
Leaving this field empty sets the symbolic link's mode bits to - 777 (rwxrwxrwx). In this case, the owner - and group fields must also be empty. -
The S Instruction for Creating a Socket - - - - - - - -
The 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 socket [owner group mode_bits] - --
where -
-
-
- S -
- Indicates the creation of a socket. It must be a capital - letter. -
- socket -
- Names the socket. The proper format depends on the local - machine's operating system. -
- 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 ls -l
- command.
-
To designate the issuer of the package command (usually, the - local superuser root) as the socket's owner, leave this field - empty. In this case, the group and mode_bits fields - must also be empty. -
- 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 ls -lg
- command.
-
To have the symbolic link's group match the default group associated - with the package command's issuer, leave this field - empty. The issuer is usually the local superuser root and - the default group is designated in the issuer's entry in the local - /etc/passwd file or equivalent. If this field is left empty, - the owner and mode_bits fields must also be empty. -
- mode_bits -
- Defines the socket's UNIX mode bits. Acceptable values are the
- standard three- or four-digit numbers corresponding to combinations of
- permissions. Examples: 755 corresponds to
- rwxr-xr-x, and 644 to rw-r--r--.
-
Leaving this field empty sets the symbolic link's mode bits to - 777 (rwxrwxrwx), modulated by the cell's - umask. In this case, the owner and group fields must - also be empty. -
The %define or %undef Instructions Declaring or Undeclaring a - Definition - - - - - - -
The %define instruction in a package configuration - file declares or defines a variable, depending on its number of - arguments: -
-
-
- If followed by a single argument, it declares that argument to be - defined. The argument is then available as a controller when mentioned - in %ifdef and %ifndef statements, which evaluate to - true and false respectively. -
- 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 - ${variable}--the package command interpreter - substitutes the second argument for it. -
The %undef statement negates the effect of a previous - %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 declaration - %define variable value - %undef declaration - %undef variable - --
where -
-
-
- %define -
- Indicates a definition statement. -
- %undef -
- Indicates a statement that negates a definition. -
- declaration -
- Names the string being declared by a %define statement, or - negated by an %undef statement. -
- variable -
- Specifies the name of the variable that a %define statement is - defining, or an %undef statement is negating. -
- value -
- 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 ${variable}), in - this or other prototype and library files. It can include one or more - words. -
The %ifdef and %ifndef Instructions for Specifying a Conditional - Action to Perform - - - - - - -
The %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 %define statement, or is a variable - for which a value has been defined by a two-argument %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 %define statement has defined it - or an %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 - false. (For an %ifdef statement, the - %else statement is executed if the indicated string has never been - declared or is a variable without a value, or if an %undef - statement has undefined either one; for an %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 - %ifndef statements. -
The two types of statement share a common syntax: -
%ifdef | ifndef declaration - action+ - [%else [declaration] - alternate_action+] - %endif declaration - --
where -
-
-
- ifdef -
- Indicates that the statement evaluates as true if the string in - the declaration field is declared or is a variable with a defined - value. -
- ifndef -
- 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. -
- declaration -
- Specifies the string that must be declared or the variable name that must - have a defined value for an %ifdef statement to evaluate as - true, which results in the specified action being performed. - For an %ifndef statement, the string must not be declared or the - variable must have no defined value for the statement to evaluate as - true. The first and third occurrences of - declaration (the latter following the string %endif) are - required. The second occurrence (following the string %else) - is optional, serving only to clarify to which %ifdef or - %ifndef statement the %else statement belongs. -
- action -
- Specifies each action to perform if the %ifdef or - %ifndef statement evaluates as true. Each action - must appear on a separate line. Acceptable types of actions are other - statements beginning with a percent sign and definition instructions. -
- alternate_action -
- Specifies each action to perform if the %ifdef or - %ifndef statement evaluates to false. Each action - must appear on a separate line. Acceptable types of actions are other - statements beginning with a percent sign and definition instructions. -
The %include Instruction for Including a Library File - - - -
The %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 - %include instruction appears. It has the following - syntax: -
%include pathname - --
where -
-
-
- %include -
- Indicates a library file include statement. -
- 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. -
Cautions -
The configuration file must be completely correct. If there are any - syntax errors or incorrect values, the package command interpreter - exits without executing any instruction. -
Examples -
The following example B and C instructions define a - disk /dev/hd0a with major and minor device numbers 1 and - 0 and mode bits of -rw-r--r--, and a tty - /dev/ttyp5 with major and minor device numbers 6 and - 5 and mode bits of -rw-rw-rw. In both cases, the - owner is root and the owning group 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 - /usr directory with owner root and group - wheel and mode bits of drwxr-xr-x. The - R update code removes any files and subdirectories that reside in - the /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 /bin/grep, using - /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 - /usr/vice/etc/ThisCell file and specifies an absolute pathname for - the source file, as indicated by the A update code. The - Q code makes the package command return status code 4 as - it exits, prompting a reboot of the machine if the standard - 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 /etc/ftpd on the local disk to the file - /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 - /dev/printer. -
- S /dev/printer root wheel 777 - --
The following example %define instruction defines the value for - the variable ${diskmode}. This variable is used elsewhere in - the template to fill the owner_name, group_name, and - mode_bits fields in a D, F, or L - instruction. -
%define diskmode root wheel 644 - --
The following example %undef instruction declares the string - afsd not to be defined. -
%undef afsd - --
The following example %ifdef instruction specifies that if the - string 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 - %define statements earlier in the prototype file to declare - rs_aix42 and to assign a value to the ${wsadmin} - variable. -
%ifdef rs_aix42
- %include ${wsadmin}/lib/rs_aix42.readonly
- %include ${wsadmin}/lib/rs_aix42.generic
- %include ${wsadmin}/lib/rs_aix42.generic.dev
- %endif rs_aix42
-
-
- The following example %ifndef instruction, appropriate for the - State University cell, defines stateu.edu as the value of - the ${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 base.generic from the lib subdirectory of - the directory in which package-related files reside. The - ${wsadmin} variable resolves to an actual pathname (such as - /afs/abc.com/wsadmin) during compilation. -
%include ${wsadmin}/lib/base.generic
-
-
- Related Information -
package -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf054.htm diff -c openafs/doc/html/AdminReference/auarf054.htm:1.1 openafs/doc/html/AdminReference/auarf054.htm:removed *** openafs/doc/html/AdminReference/auarf054.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf054.htm Thu Oct 2 10:12:22 2008 *************** *** 1,343 **** - - -
Administration Reference
-
-
-
uss Bulk Input File
- - - -Purpose -
Provides instructions for the uss bulk command -
Description -
The uss bulk input file lists instructions for the - uss command interpreter to execute when running the uss - bulk command. If the file includes add instructions - that reference a uss template file, then the template file must - also exist. -
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. -
-
-
- add -
- Creates a user account. Equivalent to the uss add - command. -
- delete -
- Deletes a user account. Equivalent to the uss delete - command. -
- delvolume -
- Removes the volume and VLDB entry for each account referenced by a - delete instruction that follows this instruction in the bulk input - file. -
- exec -
- Executes a command. -
- savevolume -
- Preserves the volume and VLDB entry for each account referenced by a - delete instruction that follows this instruction in the bulk input - file. -
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 uss add command - issued on the command line. The order of the instruction's fields - matches the order of arguments to the uss add command, although - some arguments do not have a corresponding field. Like the uss - add command's arguments, many of the fields correspond to (provide - a value for) a variable in the 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 add - instruction must appear on a single line in the bulk input file. -
add username[:full_name][:initial_password][: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. -
-
-
- username -
- Names the user's Authentication Database and Protection Database
- entries. It can include up to eight alphanumeric characters, but not
- the : (colon), . (period), or @
- (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: - -user. Corresponding variable in the template file: - $USER. -
- 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 username field.
-
Corresponding argument to the uss add command: - -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 (/etc/passwd - or equivalent), and this variable can be used to pass a value to be used in - that field. -
- 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 changeme.
-
Corresponding argument to the uss add command: - -pass. Corresponding variable in the template file: - none. -
- password_expires -
- Sets the number of days after a user's password is changed that it
- remains valid. Provide an integer from the range 1 through
- 254 to specify the number of days until expiration, or the value
- 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 kpasswd - command to change the password (after that, only an administrator can change - it). -
Corresponding argument to the uss add command: - -pwexpires. Corresponding variable in the template - file: $PWEXPIRES. -
- 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,
- 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: - -server. Corresponding variable in the template file: - $SERVER. -
- partition -
- 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,
- /vicepa, or use one of the following abbreviations:
-
/vicepa = vicepa = a = 0 - /vicepb = vicepb = b = 1 - -
--
After /vicepz (for which the index is 25) comes -
/vicepaa = vicepaa = aa = 26 - /vicepab = vicepab = ab = 27 - -
-and so on through -
/vicepiv = vicepiv = iv = 255 - -
-Corresponding argument to the uss add command: - -partition. Corresponding variable in template: - $PART. -
- mount_point -
- Specifies the complete pathname for the user's home directory.
-
Corresponding argument to the uss add command: - -mount. -
Corresponding variable in template: $MTPT, but in the template - file's V instruction only. Occurrences of the $MTPT - variable in template instructions that follow the V instruction - take their value from the 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 V - instruction only if the string $MTPT appears alone in the V - instruction's mount_point field. -
- 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
- max user id counter (use the pts
- listmax command to display the counter). If including this
- argument, first use the 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: - -uid. Corresponding variable in template: $UID. -
- 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 uss command suite.
-
Corresponding argument to the uss add command: - -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. -
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 uss delete command issued on the command line. The order - of the instruction's fields matches the order of arguments to the - uss delete command: -
delete username:mount_point_path[:{ savevolume | delvolume }][:]
-
-
- where -
-
-
- username -
- Names the entry to delete from the Protection and Authentication - Databases. -
- mount_point_path -
- 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 savevolume string in the instruction's third field, or - precede this delete instruction with a savevolume - instruction. Partial pathnames are interpreted relative to the current - working directory. -
- savevolume -
- Retains the volume on its file server machine, and the corresponding entry - in the VLDB. Provide this value or delvolume in the third - field, or omit both values to treat the volume according to the prevailing - default, which is set by a preceding savevolume or - delvolume instruction in the bulk input file. -
- delvolume -
- Removes the volume from its file server machine, and the corresponding - entry from the VLDB. Provide this value or savevolume in the - third field, or omit both values to treat the volume according to the - prevailing default, which is set by a preceding savevolume or - delvolume instruction in the bulk input file. -
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 -
The exec instruction executes the specified command, which can - be a UNIX shell script or command, a program, or an AFS command. The - 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 uss bulk command. -
The instruction's syntax is as follows: -
exec command - --
The delvolume and savevolume Instructions for Setting the Default - Treatment of Volumes - - - - -
The savevolume and delvolume instructions determine - the default treatment of volumes referenced by the 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 delete instruction that follow it in the - bulk input file, and the delvolume instruction removes the volume - and VLDB entry for all subsequent 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; delete instructions that appear - before the first savevolume instruction are also subject to this - default. If a delete instruction's third field - specifies either savevolume or delvolume, that setting - overrides the default. -
Examples -
The following example add instruction creates an - authentication-only account. The user's initial password is - changeme (the default). -
add anderson - --
The following example add instructions refer to the indicated - 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 - smith in the Protection and Authentication Databases, with an - initial password changeme and a value for $UID provided by the - Protection Server. The volume user.smith resides on - partition /vicepa of file server machine - fs1.abc.com and is mounted at - /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 jones is similar, except - that the volume resides on partition /vicepc of file server machine - fs3.abc.com and is mounted at - /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 a and - 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 - 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 - delete instructions combined with a savevolume - instruction. Because the delete instruction for users - smith, pat, and rogers appear before the - savevolume instruction and the third field is blank in each, the - corresponding home volumes are removed. The volume for user - terry is retained because the default established by the - savevolume instruction applies to it, but user - johnson's volume is removed because the third field of her - delete instruction overrides the current default. -
delete smith:/afs/abc.com/usr/smith - delete pat:/afs/abc.com/usr/pat - delete rogers:/afs/abc.com/usr/rogers - savevolume - delete terry:/afs/abc.com/usr/terry - delete johnson:/afs/abc.com/usr/johnson:delvolume - --
The following example exec instruction appears between sets of - add and delete instructions in a bulk input file. - A message appears in the command shell where the uss bulk command - is issued, to indicate when the additions are finished and the deletions - beginning. -
exec echo "Additions completed; beginning deletions..." - --
Related Information -
uss add -
uss bulk -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf055.htm diff -c openafs/doc/html/AdminReference/auarf055.htm:1.1 openafs/doc/html/AdminReference/auarf055.htm:removed *** openafs/doc/html/AdminReference/auarf055.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf055.htm Thu Oct 2 10:12:22 2008 *************** *** 1,759 **** - - -
Administration Reference
-
-
-
uss Template File
-Provides instructions for the uss add command -
Description -
The uss template file defines the components of an AFS user - account that the uss add command (or add instruction in - a uss bulk input file) creates. Use the -template - argument to the uss add or uss bulk command to identify - the template file. -
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. -
-
-
- A -
- Imposes restrictions on user passwords and authentication attempts -
- D -
- Creates a directory -
- E -
- Creates a single-line file -
- F -
- Creates a file by copying a prototype -
- G -
- Defines a directory that is one of a set of parent directories into which - the uss command interpreter evenly distributes newly created home - directories -
- L -
- Creates a hard link -
- S -
- Creates a symbolic link -
- V -
- Creates a volume, mounts it in the file space and sets the ACL on the - mount point -
- X -
- Executes a command -
If the template file is empty (zero-length), the uss add command - or 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 uss add command's -user - argument, or in the bulk input file add instruction's - username field. -
The A Instruction for Setting the Default Treatment of Volumes - - - - - - - -
The 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 IBM AFS Administration Guide and the kas - setfields reference page. -
-
-
- Limiting the user's password lifetime. When the lifetime - expires, the user can no longer authenticate using that password, and must - change it. -
- Prohibiting the reuse of the user's 20 most recently used - passwords. -
- 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 account lockout). For regular user - accounts in most cells, the recommended limit is nine and lockout time is 25 - minutes. -
The instruction has the following syntax: -
A username password_lifetime password_reuse failures locktime - --
where -
-
-
- A -
- Indicates a security-enhancing instruction. It must be a capital - letter. -
- username -
- Names the Authentication Database entry on which to impose security - restrictions. Specify the value $USER to read in the - username from the uss add command's -user argument, - or from the username field of an add instruction in a bulk - input file. -
- password_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
- unable to authenticate, but has 30 more days in which to issue the
- kpasswd command to change the password (after that, only an
- administrator can change it).
-
Specify an integer from the range 1 through 254 to - specify the number of days until expiration, the value 0 to - indicate that the password never expires, or the value $PWEXPIRES - to read in the number of days from the uss add or uss - bulk command's -pwexpires argument. If the - A instruction does not appear in the template file, the default is - for the user's password never to expire. -
- password_reuse -
- Determines whether or not the user can change his or her password (using - the kpasswd or kas setpassword command) to one that is - similar to any of the last twenty passwords. The acceptable values are - reuse to allow reuse and noreuse to prohibit it. - If the A instruction does not appear in the template file, the - default is to allow password reuse. -
- failures -
- Sets the number of consecutive times the user can provide an incorrect
- password during authentication (using the 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 locktime field.
-
Specify an integer from the range 1 through 254 to - specify the number of failures permitted, or the value 0 to - indicate that there is no limit to the number of unsuccessful attempts. - If the A instruction does not appear in the template file, the - default is to allow an unlimited number of failures. -
- locktime -
- Specifies how long the Authentication Server refuses authentication
- attempts from a user who has exceeded the failure limit set in the
- failures field.
-
Specify a number of hours and minutes (hh:mm) or minutes - only (mm), from the range 01 (one minute) through - 36:00 (36 hours). The Authentication Server - automatically reduces any larger value to 36:00 and also - rounds up any non-zero value to the next higher multiple of 8.5 - minutes. A value of 0 (zero) sets an infinite lockout - time; an administrator must always issue the kas unlock - command to unlock the account. -
The D Instruction for Creating a Directory - - - - - - - - - - - -
The 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 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 - V instruction (notably, the $MTPT variable), the instruction must - follow the 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 uss command is - issued, it is not recommended. The preferred method for automated - creation of directories on a local disk is the package - program. Two complications arise if the pathname field refers - to a local disk directory: -
-
-
- 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 ACL field. -
- 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 - root. For local disk directories, only the local superuser - root is allowed to issue the UNIX chown command that the - 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 uss command). The issuer must then also use the - -admin argument to the uss add or uss bulk - command to authenticate as a privileged AFS administrator, which is required - for creating the Authentication Database and Protection Database entries that - the uss command interpreter always creates for a new - account. -
The instruction has the following syntax: -
D pathname mode_bits owner ACL - --
where -
-
-
- D -
- Indicates a directory creation instruction. It must be a capital - letter. -
- pathname -
- 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, - /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 fs mkmount command. -
- 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: 755 corresponds to - rwxr-xr-x, and 644 to rw-r--r--. The - first (owner) x bit must be turned on to enable access to a - directory. -
- 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 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 uss command's issuer, unless the - issuer is logged in as the local superuser root. -
- 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
- 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 $USER all. -
It is not possible to grant any permissions to the issuer of the - uss command. As the last step in account creation, the - uss command interpreter automatically deletes that person from any - ACLs set during the creation process. -
The E Instruction for Creating a Single-line File - - - - - - -
The 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 V - instruction in the template file, or in a subdirectory created by a - D instruction. -
Any number of E instructions can appear in the template - file. If the file resides in a directory created by a D - instruction, the E instruction must follow the D - instruction in the file. -
The E and F instructions have complementary - advantages. The character string echoed into the file by an - E instruction can be customized for each user, because it can - include the standard variables for which the uss command - interpreter substitutes the values specified by arguments to the uss - add command or fields in a bulk input file add - instruction. In contrast, a file created using the F - instruction cannot include variables and so has the same content for all - users. However, a file created by an 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 uss command is - issued, it is not recommended. The preferred method for automated - creation of files on a local disk is the 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 root. For local disk files, only the local - superuser root is allowed to issue the UNIX chown - command that the 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 uss command). The issuer must then also - use the -admin argument to the uss add or uss - bulk command to authenticate as a privileged AFS administrator, which is - required for creating the Authentication Database and Protection Database - entries that the uss command interpreter always creates for a new - account. -
The instruction has the following syntax: -
E pathname mode_bits owner "contents" - --
where -
-
-
- E -
- Indicates a file creation instruction. It must be a capital - letter. -
- pathname -
- 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, - /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 fs mkmount command. -
- mode_bits -
- Sets the file's UNIX mode bits. Acceptable values are the - standard three- or four-digit numbers corresponding to combinations of - permissions. Examples: 755 corresponds to - rwxr-xr-x, and 644 to rw-r--r--. -
- 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 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 uss command's issuer; otherwise, the account - creation operation halts immediately. -
- 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. -
The F Instruction for Creating a File - from a Prototype - - - - - - -
The 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 V instruction in the template file, or in a - subdirectory created by a D instruction. -
Any number of F instructions can appear in the template - file. If the file resides in a directory created by a D - instruction, the F instruction must follow the D - instruction in the file. -
The E and F instructions have complementary - advantages. A file created using the F instruction has the - same content for all users, whereas a file created by an E - instruction can be customized for each user if it includes variables. - However, a file created by an E instruction can be a single line - only, whereas the prototype file copied by an 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 uss command is - issued, it is not recommended. The preferred method for automated - creation of files on a local disk is the 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 root. For local disk files, only the local - superuser root is allowed to issue the UNIX chown - command that the 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 uss command). The issuer must then also - use the -admin argument to the uss add or uss - bulk command to authenticate as a privileged AFS administrator, which is - required for creating the Authentication Database and Protection Database - entries that the uss command interpreter always creates for a new - account. -
The instruction has the following syntax: -
F pathname mode_bits owner prototype_file - --
where -
-
-
- F -
- Indicates a file creation instruction. It must be a capital - letter. -
- 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, - /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 fs mkmount command. -
- mode_bits -
- Sets the file's UNIX mode bits. Acceptable values are the - standard three- or four-digit numbers corresponding to combinations of - permissions. Examples: 755 corresponds to - rwxr-xr-x, and 644 to rw-r--r--. -
- 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 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 uss command's issuer; otherwise, the account - creation operation halts immediately. -
- 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 pathname field. -
The G Instruction for Facilitating Even - Distribution of Home Directories - - - - - - -
The G instruction in a uss template file creates a - directory as one of the set of directories from which the 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 V instruction, the command - interpreter substitutes for it the directory defined by a 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 uss in the - IBM AFS Administration Guide for more information. -
Any number of G instructions can appear in the template - file. If the V instruction includes the $AUTO variable, it - must appear after all of the G instructions in the file. -
The instruction has the following syntax: -
G directory - --
where -
-
-
- G -
- Indicates an instruction that creates a directory to be considered as a - value for the $AUTO variable. It must be a capital letter. -
- directory -
- 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 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 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, /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 fs mkmount - command. -
The L and S Instructions for Creating a Link - - - - - - - - - - - - - -
The L instruction in a uss template file creates a - hard link between two files, as achieved by the standard UNIX ln - command. The S instruction creates a symbolic link between - two files, as achieved by the standard UNIX 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 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 D instruction, or if the existing file was created by - an E or F instruction, the L or S - instruction must follow the D, E, or F - instruction. -
The instructions share the following syntax: -
L existing_file link - S existing_file link - --
where -
-
-
- L -
- Indicates a hard link creation instruction. It must be a capital - letter. -
- S -
- Indicates a symbolic link creation instruction. It must be a - capital letter. -
- existing_file -
- Specifies the complete pathname of the existing file. -
- 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, - /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 fs mkmount command. -
The V Instruction for Creating and - Mounting a Volume - - - - - - - - - - - - - - - - - - - -
The 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 G instructions if the $AUTO variable appears in - it. (The V instruction is not necessarily the first line in - the template. If the template includes the $AUTO variable, then the - G instructions which provide values for the variable must precede - it in the file.) -
The instruction has the following syntax: -
V volume_name server partition quota mount_point owner ACL - --
where -
-
-
- V -
- Indicates a volume creation instruction. It must be a capital - letter. -
- volume_name -
- Specifies the volume's name. To follow the convention for AFS - user volume names, specify the value user.$USER. - Provide a value for the $USER variable via the uss add - command's -user argument or the username field in the - bulk input file add instruction. -
- 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, 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 uss add command's -server argument, specify the - value $SERVER. -
- partition -
- 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, /vicepa)
- or use or use one of the following abbreviations.
-
/vicepa = vicepa = a = 0 - /vicepb = vicepb = b = 1 - -
--
After /vicepz (for which the index is 25) comes -
/vicepaa = vicepaa = aa = 26 - /vicepab = vicepab = ab = 27 - -
-and so on through -
/vicepiv = vicepiv = iv = 255 - -
-To read in the value from the uss add command's - -partition argument, specify the value $PART. -
- 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 (1024 equals a megabyte), or use one of - the number variables ($1 through $9) to assign different values to different - volumes. -
- 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.
-
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, - /afs/.abc.com). If the $AUTO variable appears - in this field, the directories named by each 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 fs mkmount command.. -
-Note: If used, the $MTPT variable in this field takes its value from the uss - add command's -mount argument or from the - mount_point field of an add instruction in the bulk input - file. However, subsequent uses of the $MTPT variable (usually in - following D, E, or F instructions) take as - their value the complete contents of this field. - - 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 ls -ld - command. To follow the convention for home directory ownership, place - the value $UID in this field. -
- 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 fs setacl reference page
- describes the available permissions.
-
Grant all permissions to the new user at least. The appropriate - value is $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 uss command. As the last step in account - creation, the uss command interpreter automatically deletes that - user from any ACLs set during the creation process. -
The X Instruction for Running a - Command - - - -
The 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 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. -
The instruction has the following syntax: -
X "command" - --
where -
-
-
- X -
- Indicates a command execution instruction. It must be a capital - letter. -
- 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. -
Examples -
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 -user argument to the uss - add command or from the username field in each add - instruction in a bulk input file. -
A $USER 254 noreuse 9 25:30 - --
The following example D instruction creates a directory called - 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 - username.etcp. The contents are an entry - suitable for incorporating into the cell's global - /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 .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 G instructions: -
G usr1 - G usr2 - G usr3 - --
and then put the following value in the mount_point field of the - V instruction: -
/afs/stateu.edu/$AUTO/$USER - --
Alternatively, if they include the entire directory pathname in the - G instruction: -
G /afs/stateu.edu/usr1 - G /afs/stateu.edu/usr2 - G /afs/stateu.edu/usr3 - --
then the mount_point field of the V instruction - specifies only the following: -
$AUTO/$USER - --
The following example L instruction creates a hard link between - the files mail and 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 Mail/outgoing in the user's - home directory to the file - /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 - user.username on the /vicepa partition - of the specified file server machine, assigning it a quota of 3000 kilobyte - blocks. The mount point is under /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 \ - /afs/abc.com/usr/$USER $UID $USER all - --
The following example X instruction mounts the backup version of - the user's volume at the OldFiles subdirectory. -
X "fs mkm /afs/abc.com/usr/$USER/OldFiles user.$USER.backup" - --
Related Information -
uss add -
uss bulk -
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf056.htm diff -c openafs/doc/html/AdminReference/auarf056.htm:1.1 openafs/doc/html/AdminReference/auarf056.htm:removed *** openafs/doc/html/AdminReference/auarf056.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf056.htm Thu Oct 2 10:12:22 2008 *************** *** 1,26 **** - - -
Administration Reference
-
-
AFS System Commands
--
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf057.htm diff -c openafs/doc/html/AdminReference/auarf057.htm:1.1 openafs/doc/html/AdminReference/auarf057.htm:removed *** openafs/doc/html/AdminReference/auarf057.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf057.htm Thu Oct 2 10:12:22 2008 *************** *** 1,451 **** - - -
Administration Reference
-
-
-
afs_intro
-Purpose -
Introduction to AFS commands -
Description -
AFS provides many commands that enable users and system administrators to - use and customize its features. Many of the commands belong to the - following categories, called command suites. -
-
-
- backup -
- Interface for configuring and operating the AFS Backup System -
- bos -
- Interface to the Basic Overseer (BOS) Server for administering server - processes and configuration files -
- fs -
- Interface for administering access control lists (ACLs), the Cache - Manager, and other miscellaneous file system functions -
- fstrace -
- Interface for tracing Cache Manager operations when debugging problems -
- kas -
- Interface to the Authentication Server for administering security and - authentication information -
- pts -
- Interface to the Protection Server for administering AFS ID and group - membership information -
- uss -
- Interface for automated administration of user accounts -
- vos -
- Interface to the Volume Server and Volume Location (VL) Server for - administering volumes -
In addition, there are several commands that do not belong to - suites. -
AFS Command Syntax
-AFS commands that belong to suites have the following - structure: -
command_suite operation_code -switch <value>[+] [-flag] - --
Command Names
-Together, the command_suite and operation_code - make up the command name. -
The command_suite specifies the group of related commands to - which the command belongs, and indicates which command interpreter and server - process perform the command. AFS has several command suites, including - bos, fs, kas, package, - pts, scout, uss and vos. - Some of these suites have an interactive mode in which the issuer omits the - command_suite portion of the command name. -
The operation_code tells the command interpreter and server - process which action to perform. Most command suites include several - operation codes. The IBM AFS Administration Reference - describes each operation code in detail, and the IBM AFS Administration - Guide describes how to use them in the context of performing - administrative tasks. -
Several AFS commands do not belong to a suite and so their names do not - have a command_suite portion. Their structure is otherwise - similar to the commands in the suites. -
Options
-The term option refers to both arguments and flags, which - are described in the following sections. -
Arguments
-One or more arguments can follow the command name. Arguments - specify the entities on which to act while performing the command (for - example, which server machine, server process, or file). To minimize - the potential for error, provide a command's arguments in the order - prescribed in its syntax definition. -
Each argument has two parts, which appear in the indicated order: -
-
-
- The switch specifies the argument's type and is preceded - by a hyphen ( - ). For instance, the switch - -server usually indicates that the argument names a server - machine. Switches can often be omitted, subject to the rules outlined - in Conditions for Omitting Switches. -
- The value names a particular entity of the type specified by - the preceding switch. For example, the proper value for a - -server switch is a server machine name like - fs3.abc.com. Unlike switches (which have a - required form), values vary depending on what the issuer wants to - accomplish. Values appear surrounded by angle brackets (< - >) in command descriptions and the online help to show that they are - user-supplied variable information. -
Some arguments accept multiple values, as indicated by trailing plus sign ( - + ) in the command descriptions and online help. How many of - a command's arguments take multiple values, and their ordering with - respect to other arguments, determine when it is acceptable to omit - switches. See Conditions for Omitting Switches. -
Some commands have optional as well as required arguments; the command - descriptions and online help show optional arguments in square brackets ([ - ]). -
Flags
-Some commands have one or more flags, which specify the manner in which - the command interpreter and server process perform the command, or what kind - of output it produces. Flags are preceded by hyphens like switches, but - they take no values. Although the command descriptions and online help - generally list a command's flags after its arguments, there is no - prescribed order for flags. They can appear anywhere on the command - line following the operation code, except in between the parts of an - argument. Flags are always optional. -
An Example Command
-The following example illustrates the different parts - of a command that belongs to an AFS command suite. -
% bos getdate -server fs1.abc.com -file ptserver kaserver - --
where -
-
-
- bos is the command suite. The BOS Server executes most - of the commands in this suite. -
- getdate is the operation code. It tells the BOS Server - on the specified server machine (in this case - fs1.abc.com) to report the modification dates of - binary files in the local /usr/afs/bin directory. -
- -server fs1.abc.com is one argument, with - -server as the switch and fs1.abc.com as - the value. This argument specifies the server machine on which BOS - Server is to collect and report binary dates. -
- -file ptserver kaserver is an argument that takes multiple - values. The switch is -file and the values are - ptserver and kaserver. This argument tells the - BOS Server to report the modification dates on the files - /usr/afs/bin/kaserver and /usr/afs/bin/ptserver. -
Rules for Entering AFS Commands
-Enter each AFS command on a single line (press - <Return> only at the end of the command). Some commands - in this document appear broken across multiple lines, but that is for - legibility only. -
Use a space to separate each element on a command line from its - neighbors. Spaces rather than commas also separate multiple values of - an argument. -
In many cases, the issuer of a command can reduce the amount of typing - necessary by using one or both of the following methods: -
-
-
- Omitting switches -
- Using accepted abbreviations for operation codes, switches (if they are - included at all), and some types of values -
The following sections explain the conditions for omitting or shortening - parts of the command line. It is always acceptable to type a command in - full, with all of its switches and no abbreviations. -
Conditions for Omitting Switches: - It is always acceptable to type the switch part of an - argument, but in many cases it is not necessary. Specifically, switches - can be omitted if the following conditions are met. -
-
-
- All of the command's required arguments appear in the order - prescribed by the syntax statement -
- No switch is provided for any argument -
- There is only one value for each argument (but note the important - exception discussed in the following paragraph) -
Omitting switches is possible only because there is a prescribed order for - each command's arguments. When the issuer does not include - switches, the command interpreter relies instead on the order of - arguments; it assumes that the first element after the operation code is - the command's first argument, the next element is the command's - second argument, and so on. The important exception is when a - command's final required argument accepts multiple values. In this - case, the command interpreter assumes that the issuer has correctly provided - one value for each argument up through the final one, so any additional values - at the end belong to the final argument. -
The following list describes the rules for omitting switches from the - opposite perspective: an argument's switch must be provided when - any of the following conditions apply. -
-
-
- The command's arguments do not appear in the prescribed order -
- An optional argument is omitted but a subsequent optional argument is - provided -
- A switch is provided for a preceding argument -
- More than one value is supplied for a preceding argument (which must take - multiple values, of course); without a switch on the current argument, - the command interpreter assumes that the current argument is another value for - the preceding argument -
An Example of Omitting Switches: - Consider again the example command from An Example Command. -
% bos getdate -server fs1.abc.com -file ptserver kaserver - --
This command has two required arguments: the server machine name - (identified by the -server switch) and binary file name (identified - by the -file switch). The second argument accepts multiple - values. By complying with all three conditions, the issuer can omit the - switches: -
% bos getdate fs1.abc.com ptserver kaserver - --
Because there are no switches, the bos command interpreter - relies on the order of arguments. It assumes that the first element - following the operation code, fs1.abc.com, is the - server machine name, and that the next argument, ptserver, is a - binary file name. Then, because the command's second (and last) - argument accepts multiple values, the command interpreter correctly interprets - kaserver as an additional value for it. -
On the other hand, the following is not acceptable because it violates the - first two conditions in Conditions for Omitting Switches: even though there is only one value per argument, the - arguments do not appear in the prescribed order, and a switch is provided for - one argument but not the other. -
% bos getdate ptserver -server fs1.abc.com - --
Rules for Using Abbreviations and Aliases
-This section explains how to abbreviate operation codes, - option names, server machine names, partition names, and cell names. It - is not possible to abbreviate other types of values. -
Abbreviating Operation Codes: - It is acceptable to abbreviate an operation code to the shortest form - that still distinguishes it from the other operation codes in its - suite. -
For example, it is acceptable to shorten bos install to bos - i because there are no other operation codes in the bos - command suite that begin with the letter i. In contrast, - there are several bos operation codes that start with the letter - s, so the abbreviations must be longer to remain unambiguous: -
-
-
bos sa for bos salvage -
bos seta for bos setauth -
bos setc for bos setcellname -
bos setr for bos setrestart -
bos sh for bos shutdown -
bos start for bos start -
bos startu for bos startup -
bos stat for bos status -
bos sto for bos stop -
In addition to abbreviations, some operation codes have an - alias, a short form that is not derived by abbreviating the - operation code to its shortest unambiguous form. For example, the alias - for the fs setacl command is fs sa, whereas the shortest - unambiguous abbreviation is fs seta. -
There are two usual reasons an operation code has an alias: -
-
-
- Because the command is frequently issued, it is convenient to have a form - shorter than the one derived by abbreviating. The fs setacl - command is an example. -
- Because the command's name has changed, but users of previous - versions of AFS know the former name. For example, bos - listhosts has the alias bos getcell, its former name. - It is acceptable to abbreviate aliases to their shortest unambiguous form (for - example, bos getcell to bos getc). -
Even if an operation code has an alias, it is still acceptable to use the - shortest unambiguous form. Thus, the fs setacl command has - three acceptable forms: fs setacl (the full form), fs - seta (the shortest abbreviation), and fs sa (the - alias). -
Abbreviating Switches and Flags: - It is acceptable to shorten a switch or flag to the shortest form that - distinguishes it from the other switches and flags for its operation - code. It is often possible to omit switches entirely, subject to the - conditions listed in Conditions for Omitting Switches. -
Abbreviating Server Machine Names: - AFS server machines must have fully-qualified - Internet-style host names (for example, fs1.abc.com), - but it is not always necessary to type the full name on the command - line. AFS commands accept unambiguous shortened forms, but depend on - the cell's name service (such as the Domain Name Service) or a local host - table to resolve a shortened name to the fully-qualified equivalent when the - command is issued. -
Most commands also accept the dotted decimal form of the machine's IP - address as an identifier. -
Abbreviating Partition Names: - Partitions that house AFS volumes must have names of - the form /vicepx or /vicepxx, where - the variable final portion is one or two lowercase letters. By - convention, the first server partition created on a file server machine is - called /vicepa, the second /vicepb, and so on. - The IBM AFS Quick Beginnings explains how to configure and name a - file server machine's partitions in preparation for storing AFS volumes - on them. -
When issuing AFS commands, you can abbreviate a partition name using any of - the following forms: -
/vicepa = vicepa = a = 0 - /vicepb = vicepb = b = 1 - --
After /vicepz (for which the index is 25) comes -
/vicepaa = vicepaa = aa = 26 - /vicepab = vicepab = ab = 27 - --
and so on through -
/vicepiv = vicepiv = iv = 255 - --
Abbreviating Cell Names: - A cell's full name usually matches its Internet - domain name (such as stateu.edu for the State University or - abc.com for ABC Corporation). Some AFS commands - accept unambiguous shortened forms, usually with respect to the local - /usr/vice/etc/CellServDB file but sometimes depending on the - ability of the local name service to resolve the corresponding domain - name. -
Displaying Online Help for AFS Commands
-To display online help for AFS commands that belong to - suites, use the help and apropos operation codes. - A -help flag is also available on every almost every AFS - command. -
The online help entry for a command consists of two or three lines: -
-
-
- The first line names the command and briefly describes what it does -
- If the command has aliases, they appear on the next line -
- The final line, which begins with the string Usage:, - lists the command's options in the prescribed order; online help - entries use the same typographical symbols (brackets and so on) as this - documentation. -
If no operation code is specified, the help operation code - displays the first line (short description) for every operation code in the - suite: -
- % command_suite help - --
If the issuer specifies one or more operation codes, the help - operation code displays each command's complete online entry (short - description, alias if any, and syntax): -
- % command_suite help operation_code+ - --
The -help flag displays a command's syntax but not the - short description or alias: -
% command_name -help - --
The apropos operation code displays the short description of any - command in a suite whose operation code or short description includes the - specified keyword: -
% command_suite apropos "<help string>" - --
The following example command displays the complete online help entry for - the fs setacl command: -
- % fs help setacl - fs setacl: set access control list - aliases: sa - Usage: fs setacl -dir <directory>+ -acl <access list entries>+ - [-clear] [-negative] [-id] [-if] [-help] - --
To see only the syntax statement, use the -help flag: -
% fs setacl -help - Usage: fs setacl -dir <directory>+ -acl <access list entries>+ - [-clear] [-negative] [-id] [-if] [-help] - --
In the following example, a user wants to display the quota for her home - volume. She knows that the relevant command belongs to the - fs suite, but cannot remember the operation code. She uses - quota as the keyword: -
- % fs apropos quota - listquota: list volume quota - quota: show volume quota usage - setquota: set volume quota - --
The following illustrates the error message that results if no command name - or short description contains the keyword: -
- % fs apropos "list quota" - Sorry, no commands found - --
Privilege Required -
Many AFS commands require one or more types of administrative - privilege. See the reference page for each command. -
Related Information -
-
-
afsd -
backup -
bos -
buserver -
butc -
dlog -
dpass -
fms -
fs -
fstrace -
kas -
kaserver -
kdb -
klog -
knfs -
kpasswd -
kpwvalid -
package -
package -
pagsh -
pts -
ptserver -
runntp -
rxdebug -
salvager -
scout -
sys -
tokens -
unlog -
up -
upclient -
upserver -
uss -
vlserver -
volinfo -
vos -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf058.htm diff -c openafs/doc/html/AdminReference/auarf058.htm:1.1 openafs/doc/html/AdminReference/auarf058.htm:removed *** openafs/doc/html/AdminReference/auarf058.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf058.htm Thu Oct 2 10:12:22 2008 *************** *** 1,433 **** - - -
Administration Reference
-
-
-
afsd
- - - - - - - - -Purpose -
Initializes the Cache Manager and starts related daemons. -
Synopsis -
afsd [-blocks <1024 byte blocks in cache>] - [-files <files in cache>] - [-rootvol <name of AFS root volume>] - [-stat <number of stat entries>] - [-memcache] [-cachedir <cache directory>] - [-mountdir <mount location>] - [-daemons <number of daemons to use>] - [-nosettime] [-verbose] [-rmtsys] [-debug] - [-chunksize <log(2) of chunk size>] - [-dcache <number of dcache entries>] - [-volumes <number of volume entries>] - [-biods <number of bkg I/O daemons (aix vm)>] - [-prealloc <number of 'small' preallocated blocks>] - [-confdir <configuration directory>] - [-logfile <Place to keep the CM log>] - [-waitclose] [-shutdown] [-enable_peer_stats] - [-enable_process_stats] [-help] --
This command does not use the syntax conventions of the AFS command - suites. Provide the command name and all option names in full. -
Description -
The afsd command initializes the Cache Manager on an AFS client - machine by transferring AFS-related configuration information into kernel - memory and starting several daemons. More specifically, the - afsd command performs the following actions: -
-
-
- Sets a field in kernel memory that defines the machine's cell - membership. Some Cache Manager-internal operations and system calls - consult this field to learn which cell to execute in. (The AFS command - interpreters refer to the /usr/vice/etc/ThisCell file - instead.) This information is transferred into the kernel from the - /usr/vice/etc/ThisCell file and cannot be changed until the - afsd program runs again. -
- Places in kernel memory the names and Internet addresses of the database
- server machines in the local cell and (optionally) foreign cells. The
- appearance of a cell's database server machines in this list enables the
- Cache Manager to contact them and to access files in the cell. Omission
- of a cell from this list, or incorrect information about its database server
- machines, prevents the Cache Manager from accessing files in it.
-
The list of database server machines is transferred into the kernel from - the /usr/vice/etc/CellServDB file. After initialization, use - the fs newcell command to change the kernel-resident list without - having to reboot. -
- Mounts the root of the AFS filespace on a directory on the machine's - local disk, according to either the first field in the - /usr/vice/etc/cacheinfo file (the default) or the afsd - command's -mountdir argument. The conventional value is - /afs. -
- Determines which volume to mount at the root of the AFS file tree. - The default is the volume root.afs; use the - -rootvol argument to override it. Although the base - (read/write) form of the volume name is the appropriate value, the Cache - Manager has a bias for accessing the read-only version of the volume (by - convention, root.afs.readonly) if it is - available. -
- Configures the cache on disk (the default) or in machine memory if the - -memcache argument is provided. In the latter case, the - afsd program allocates space in machine memory for caching, and the - Cache Manager uses no disk space for caching even if the machine has a - disk. -
- Defines the name of the local disk directory devoted to caching, when the
- -memcache argument is not used. If necessary, the
- afsd program creates the directory (its parent directory must
- already exist). It does not remove the directory that formerly served
- this function, if one exists.
-
The second field in the /usr/vice/etc/cacheinfo file is the - source for this name, and the standard value is the /usr/vice/cache - directory. Use the -cachedir argument to override the value - in the cacheinfo file. -
- Sets the size of the cache. The default source for the value is the
- third field in the /usr/vice/etc/cacheinfo file, which specifies a
- number of kilobytes.
-
For a memory cache, the following arguments to the afsd command - override the value in the cacheinfo file: -
-
-
- The -blocks argument, to specify a different number of kilobyte - blocks. -
- The -dcache and -chunksize arguments together, to - set both the number of dcache entries and the chunk size (see below for - definition of these parameters). In this case, the afsd - program derives cache size by multiplying the two values. Using this - combination is not recommended, as it requires the issuer to perform the - calculation beforehand to determine the resulting cache size. -
- The -dcache argument by itself. In this case, the - afsd program derives cache size by multiplying the value specified - by the -dcache argument by the default memory cache chunk size of - eight kilobytes. Using this argument is not recommended, as it requires - the issuer to perform the calculation beforehand to determine the resulting - cache size. -
For satisfactory memory cache performance, the specified value must leave - enough memory free to accommodate all other processes and commands that can - run on the machine. If the value exceeds the amount of memory - available, the afsd program exits without initializing the Cache - Manager and produces the following message on the standard output - stream: -
afsd: memCache allocation failure at number KB - -
-where number is how many kilobytes were allocated just before the - failure. -
For a disk cache, use the -blocks argument to the - afsd command to override the value in the cacheinfo - file. The value specified in either way sets an absolute upper limit on - cache size; values provided for other arguments (such as - -dcache and -chunksize) never result in a larger - cache. The afsd program rejects any setting larger than 95% - of the partition size, and exits after generating an error message on the - standard output stream, because the cache implementation itself requires a - small amount of disk space and overfilling the partition can cause the client - machine to panic. -
To change the size of a disk cache after initialization without rebooting, - use the fs setcachesize command; the setting persists until - the afsd command runs again or the fs setcachesize - command is reissued. The fs setcachesize command does not - work for memory caches. -
- Sets the size of each cache 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 Vn 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. -
To override the default chunk size for either type of cache, use the - -chunksize argument to provide an integer to be used as an exponent - of two; see the Options section for details. For a - memory cache, if total cache size divided by chunk size leaves a remainder, - the afsd program rounds down 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 (Vn files) is set
- to the largest of the following unless the -files argument is used
- to set the value explicitly:
-
-
-
- 100 -
- 1.5 times the result of dividing cache size by chunk size - (cachesize/chunksize * 1.5) -
- The result of dividing cachesize by 10 KB (cachesize/10240) -
- Sets the number of dcache entries allocated in machine memory for
- storing information about the chunks in the cache.
-
For a disk cache, the /usr/vice/cache/CacheItems file contains - one entry for each Vn 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. -
For a memory cache, there is no CacheItems file so all - information about cache chunks must be in memory as dcache entries. - Thus, there is no default number of dcache entries for a memory cache; - instead, the afsd program derives it by dividing the cache size by - the chunk size. -
To set the number of dcache entries, use the -dcache - argument; the specified value can exceed the default limit of - 2,000. Using this argument is not recommended for either type of - cache. Increasing the number of dcache entries for a disk cache - sometimes improves performance (because more entries are retrieved from memory - rather than from disk), but only marginally. Using this argument for a - memory cache requires the issuer to calculate the cache size by multiplying - this value by the chunk size. -
- Sets the number of stat entries available in machine memory for - caching status information about cached AFS files. The default is - 300; use the -stat argument to override the default. -
- Randomly selects a file server machine in the local cell as the source for
- the correct time. Every five minutes thereafter, the local clock is
- adjusted (if necessary) to match the file server machine's clock.
-
Use the -nosettime flag to prevent the afsd command - from selecting a time standard. This is recommended only on file server - machines that are also acting as clients. File server machines maintain - the correct time using the Network Time Protocol Daemon instead. -
In addition to setting cache configuration parameters, the afsd - program starts the following daemons. (On most system types, these - daemons appear as nameless entries in the output of the UNIX ps - command.) -
-
-
- One callback daemon, which handles callbacks. It also - responds to the File Server's periodic probes, which check that the - client machine is still alive. -
- One maintenance daemon, which performs the following
- tasks:
-
-
-
- Garbage collects obsolete data (for example, expired tokens) from kernel - memory -
- Synchronizes files -
- Refreshes information from read-only volumes once per hour -
- Does delayed writes for NFS clients if the machine is running the NFS/AFS - Translator -
- One cache-truncation daemon, which flushes the cache when free - space is required, by writing cached data and status information to the File - Server. -
- One server connection daemon, which sends a probe to the File - Server every few minutes to check that it is still accessible. It also - synchronizes the machine's clock with the clock on a randomly-chosen file - server machine, unless the -nosettime flag is used. There is - always one server connection daemon. -
- One or more background daemons that improve performance by
- pre-fetching files and performing background (delayed) writes of saved data
- into AFS.
-
The default number of background daemons is two, enough to service at least - five simultaneous users of the machine. To increase the number, use the - -daemons argument. A value greater than six is not generally - necessary. -
- On some system types, one Rx listener daemon, which listens for - incoming RPCs. -
- On some system types, one Rx event daemon, which reviews the Rx - system's queue of tasks and performs them as appropriate. Most - items in the queue are retransmissions of failed packets. -
- On machines that run AIX with virtual memory (VM) integration, one or more
- VM daemons (sometimes called I/O daemons, which transfer
- data between disk and machine memory. The number of them depends on the
- setting of the -biods and -daemons arguments:
-
-
-
- If the -biods argument is used, it sets the number of VM - daemons. -
- If only the -daemons argument is used, the number of VM daemons - is twice the number of background daemons. -
- If neither argument is used, there are five VM daemons. -
Cautions -
Do not use the -shutdown parameter. It does not shutdown - the Cache Manager effectively. Instead, halt Cache Manager activity by - using the standard UNIX umount command to unmount the AFS root - directory (by convention, /afs). The machine must then be - rebooted to reinitialize the Cache Manager. -
Options -
-
-
- -blocks -
- Specifies the number of kilobyte blocks to be made available for caching - in the machine's cache directory (for a disk cache) or memory (for a - memory cache), overriding the default defined in the third field of the - /usr/vice/etc/cacheinfo file. For a disk cache, the value - cannot exceed 95% of the space available in the cache partition. If - using a memory cache, do not combine this argument with the -dcache - argument, since doing so can possibly result in a chunk size that is not an - exponent of 2. -
- -files -
- Specifies the number of Vn files to create in the - cache directory for a disk cache, overriding the default that is calculated as - described in the Description section. Each - Vn 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 - -memcache argument. -
- -rootvol -
- Names the read/write volume corresponding to the root directory for the - AFS file tree (which is usually the /afs directory). This - value overrides the default of the root.afs volume. -
- -stat -
- Specifies the number of entries to allocate in the machine's memory - for recording status information about the AFS files in the cache. This - value overrides the default of 300. -
- -memcache -
- Initializes a memory cache rather than a disk cache. Do not combine - this flag with the -files argument. -
- -cachedir -
- Names the local disk directory to be used as the cache. This value - overrides the default defined in the second field of the - /usr/vice/etc/cacheinfo file. -
- -mountdir -
- Names the local disk directory on which to mount the root of the AFS - filespace. This value overrides the default defined in the first field - of the /usr/vice/etc/cacheinfo file. If a value other than - the /afs directory is used, the machine cannot access the filespace - of cells that do use that value. -
- -daemons -
- Specifies the number of background daemons to run on the machine.
- These daemons improve efficiency by doing prefetching and background writing
- of saved data. This value overrides the default of 2, which is adequate
- for a machine serving up to five users. Values greater than
- 6 are not generally more effective than 6.
-
Note: On AIX machines with integrated virtual memory (VM), - the number of VM daemons is set to twice the value of this argument, if it is - provided and the -biods argument is not. If both arguments - are omitted, there are five VM daemons. -
- -nosettime -
- Prevents the Cache Manager from synchronizing its clock with the clock on - a server machine selected at random, by checking the time on the server - machine every five minutes. Use this flag only on a machine that is - already using another time synchronization protocol (for example, a server - machine that is running the runntp process). -
- -verbose -
- Generates a detailed trace of the afsd program's actions - on the standard output stream. -
- -rmtsys -
- Initializes an additional daemon to execute AFS-specific system calls on - behalf of NFS client machines. Use this flag only if the machine is an - NFS/AFS translator machine serving users of NFS client machines who execute - AFS commands. - -
- -debug -
- Generates a highly detailed trace of the afsd program's - actions on the standard output stream. The information is useful mostly - for debugging purposes. -
- -chunksize -
- Sets the size of each cache chunk. The integer provided, which must - be from the range 0 to 30, is used as an exponent on the - number 2. It overrides the default of 16 for a disk cache - (216 is 64 KB) and 13 for a memory cache (213 is 8 - KB). A value of 0 or less, or greater than 30, - sets chunk size to the appropriate default. Values less than - 10 (which sets chunk size to a 1 KB) are not recommended. - Combining this argument with the -dcache argument is not - recommended because it requires that the issuer calculate the cache size that - results. -
- -dcache -
- 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 Vn 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 - this value by the chunk size). Do not combine this argument with the - -blocks argument, since doing so can possibly result in a chunk - size that is not an exponent of 2. -
- -volumes -
- Specifies the number of memory structures to allocate for storing volume - location information. The default value is 50. -
- -biods -
- Sets the number of VM daemons dedicated to performing I/O operations on a
- machine running a version of AIX with virtual memory (VM) integration.
- If both this argument and the -daemons argument are omitted, the
- default is five. If this argument is omitted but the
- -daemons argument is provided, the number of VM daemons is set to
- twice the value of the -daemons argument.
-
-Note: Provide this argument only on a machine that runs AIX with VM - integration. - - -prealloc -
- Specifies the number of pieces of memory to preallocate for the Cache - Manager's internal use. The default initial value is 400, but the - Cache Manager dynamically allocates more memory as it needs it. -
- -confdir -
- Names a directory other than the /usr/vice/etc directory from - which to fetch the cacheinfo, ThisCell, and - CellServDB configuration files. -
- -logfile -
- Is obsolete and has no real effect. It specifies an alternate file - in which to record a type of trace that the Cache Manager no longer - generates; the default value is /usr/vice/etc/AFSLog. -
- -waitclose -
- Has no effect on the operation of the Cache Manager. The behavior - it affected in previous versions of the Cache Manager, to perform synchronous - writes to the File Server, is now the default behavior. To perform - asynchronous writes in certain cases, use the fs storebehind - command. -
- -shutdown -
- Shuts down the Cache Manager, but not in the most effective possible - way. Do not use this flag. -
- -enable_peer_stats -
- Activates the collection of Rx statistics and allocates memory for their - storage. For each connection with a specific UDP port on another - machine, a separate record is kept for each type of RPC (FetchFile, GetStatus, - and so on) sent or received. To display or otherwise access the - records, use the Rx Monitoring API. -
- -enable_process_stats -
- Activates the collection of Rx statistics and allocates memory for their - storage. A separate record is kept for each type of RPC (FetchFile, - GetStatus, and so on) sent or received, aggregated over all connections to - other machines. To display or otherwise access the records, use the Rx - Monitoring API. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Examples -
The afsd command is normally included in the machine's AFS - initialization file, rather than typed at the command shell prompt. For - most disk caches, the appropriate form is -
/usr/vice/etc/afsd - --
The following command is appropriate when enabling a machine to act as an - NFS/AFS Translator machine serving more than five users. -
/usr/vice/etc/afsd -daemons 4 -rmtsys - --
The following command initializes a memory cache and sets chunk size to 16 - KB (214). -
/usr/vice/etc/afsd -memcache -chunksize 14 - --
Privilege Required -
The issuer must be logged in as the local superuser root. -
Related Information -
Vn -
cacheinfo - - - - - -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf059.htm diff -c openafs/doc/html/AdminReference/auarf059.htm:1.2 openafs/doc/html/AdminReference/auarf059.htm:removed *** openafs/doc/html/AdminReference/auarf059.htm:1.2 Thu Jul 29 00:03:31 2004 --- openafs/doc/html/AdminReference/auarf059.htm Thu Oct 2 10:12:22 2008 *************** *** 1,329 **** - - -
Administration Reference
-
-
-
afsmonitor
-Purpose -
Monitors File Servers and Cache Managers -
Description -
afsmonitor [initcmd] [-config <configuration file>] - [-frequency <poll frequency, in seconds>] - [-output <storage file name>] [-detailed] - [-debug <turn debugging output on to the named file>] - [-fshosts <list of file servers to monitor>+] - [-cmhosts <list of cache managers to monitor>+] - [-buffers <number of buffer slots>] [-help] - - afsmonitor [i] [-co <configuration file>] - [-fr <poll frequency, in seconds>] - [-o <storage file name>] [-det] - [-deb <turn debugging output on to the named file>] - [-fs <list of file servers to monitor>+] - [-cm <list of cache managers to monitor>+] - [-b <number of buffer slots>] [-h] --
Description -
The afsmonitor command initializes a program that gathers and - displays statistics about specified File Server and Cache Manager - operations. It allows the issuer to monitor, from a single location, a - wide range of File Server and Cache Manager operations on any number of - machines in both local and foreign cells. -
There are 271 available File Server statistics and 571 available Cache - Manager statistics, listed in the appendix about afsmonitor - statistics in the IBM AFS Administration Guide. By default, - the command displays all of the relevant statistics for the file server - machines named by the -fshosts argument and the client machines - named by the -cmhosts argument. To limit the display to only - the statistics of interest, list them in the configuration file specified by - the -config argument. In addition, use the configuration - file for the following purposes: -
-
-
- To set threshold values for any monitored statistic. When the value - of a statistic exceeds the threshold, the afsmonitor command - displays it in reverse video. There are no default threshold - values. -
- To invoke a program or script automatically when a statistic exceeds its - threshold. The AFS distribution does not include any such - scripts. -
- To list the file server and client machines to monitor, instead of using - the -fshosts and -cmhosts arguments. -
For a description of the configuration file, see the afsmonitor - Configuration File reference page -
Cautions -
The following software must be accessible to a machine where the - afsmonitor program is running: -
-
-
- The AFS xstat libraries, which the afsmonitor - program uses to gather data -
- The curses graphics package, which most UNIX distributions - provide as a standard utility -
The afsmonitor screens format successfully both on so-called - dumb terminals and in windowing systems that emulate terminals. For the - output to looks its best, the display environment needs to support reverse - video and cursor addressing. Set the TERM environment variable to the - correct terminal type, or to a value that has characteristics similar to the - actual terminal type. The display window or terminal must be at least - 80 columns wide and 12 lines long. - - - -
The afsmonitor program must run in the foreground, and in its - own separate, dedicated window or terminal. The window or terminal is - unavailable for any other activity as long as the afsmonitor - program is running. Any number of instances of the - afsmonitor program can run on a single machine, as long as each - instance runs in its own dedicated window or terminal. Note that it can - take up to three minutes to start an additional instance. -
Options -
-
-
- initcmd -
- Accommodates the command's use of the AFS command parser, and is - optional. -
- -config -
- Names the configuration file which lists the machines to monitor, - statistics to display, and threshold values, if any. A partial pathname - is interpreted relative to the current working directory. Provide this - argument if not providing the -fshosts argument, - -cmhosts argument, or neither. For instructions on creating - this file, see the preceding Description section, and the section - on the afsmonitor program in the IBM AFS Administration - Guide. -
- -frequency -
- Specifies in seconds how often the afsmonitor program probes - the File Servers and Cache Managers. Valid values range from - 1 to 86400 (which is 24 hours); the default value - is 60. This frequency applies to both File Servers and Cache - Managers, but the afsmonitor program initiates the two types of - probes, and processes their results, separately. The actual interval - between probes to a host is the probe frequency plus the time required for all - hosts to respond. -
- -output -
- Names the file to which the afsmonitor program writes all of - the statistics that it collects. By default, no output file is - created. See the section on the afsmonitor command in the - IBM AFS Administration Guide for information on this file. -
- -detailed -
- Formats the information in the output file named by -output - argument in a maximally readable format. Provide the -output - argument along with this one. -
- -fshosts -
- Names one or more machines from which to gather File Server - statistics. For each machine, provide either a fully qualified host - name, or an unambiguous abbreviation (the ability to resolve an abbreviation - depends on the state of the cell's name service at the time the command - is issued). This argument can be combined with the -cmhosts - argument, but not with the -config argument. -
- -cmhosts -
- Names one or more machines from which to gather Cache Manager - statistics. For each machine, provide either a fully qualified host - name, or an unambiguous abbreviation (the ability to resolve an abbreviation - depends on the state of the cell's name service at the time the command - is issued). This argument can be combined with the -fshosts - argument, but not with the -config argument. -
- -buffers -
- Is nonoperational and provided to accommodate potential future - enhancements to the program. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Output -
The afsmonitor program displays its data on three screens: -
-
-
- System Overview: This screen appears automatically when - the afsmonitor program initializes. It summarizes separately - for File Servers and Cache Managers the number of machines being monitored and - how many of them have alerts (statistics that have exceeded their - thresholds). It then lists the hostname and number of alerts for each - machine being monitored, indicating if appropriate that a process failed to - respond to the last probe. -
- File Server: This screen displays File Server statistics - for each file server machine being monitored. It highlights statistics - that have exceeded their thresholds, and identifies machines that failed to - respond to the last probe. -
- Cache Managers: This screen displays Cache Manager - statistics for each client machine being monitored. It highlights - statistics that have exceeded their thresholds, and identifies machines that - failed to respond to the last probe. -
Fields at the corners of every screen display the following - information: -
-
-
- In the top left corner, the program name and version number. -
- In the top right corner, the screen name, current and total page numbers, - and current and total column numbers. The page number (for example, - p. 1 of 3) indicates the index of the current page and the - total number of (vertical) pages over which data is displayed. The - column number (for example, c. 1 of 235) indicates the index - of the current leftmost column and the total number of columns in which data - appears. (The symbol >>> indicates that there is additional - data to the right; the symbol <<< indicates that - there is additional data to the left.) -
- In the bottom left corner, a list of the available commands. Enter - the first letter in the command name to run that command. Only the - currently possible options appear; for example, if there is only one page - of data, the next and prev commands, which scroll the - screen up and down respectively, do not appear. For descriptions of the - commands, see the following section about navigating the display - screens. -
- In the bottom right corner, the probes field reports how many - times the program has probed File Servers (fs), Cache Managers - (cm), or both. The counts for File Servers and Cache - Managers can differ. The freq field reports how often the - program sends probes. -
Navigating the afsmonitor Display Screens -
As noted, the lower left hand corner of every display screen displays the - names of the commands currently available for moving to alternate screens, - which can either be a different type or display more statistics or machines of - the current type. To execute a command, press the lowercase version of - the first letter in its name. Some commands also have an uppercase - version that has a somewhat different effect, as indicated in the following - list. -
-
-
- cm -
- Switches to the Cache Managers screen. Available only on - the System Overview and File Servers screens. -
- fs -
- Switches to the File Servers screen. Available only on - the System Overview and the Cache Managers - screens. -
- left -
- Scrolls horizontally to the left, to access the data columns situated to - the left of the current set. Available when the <<< - symbol appears at the top left of the screen. Press uppercase - L to scroll horizontally all the way to the left (to display the - first set of data columns). -
- next -
- Scrolls down vertically to the next page of machine names. - Available when there are two or more pages of machines and the final page is - not currently displayed. Press uppercase N to scroll to the - final page. -
- oview -
- Switches to the System Overview screen. Available only - on the Cache Managers and File Servers screens. -
- prev -
- Scrolls up vertically to the previous page of machine names. - Available when there are two or more pages of machines and the first page is - not currently displayed. Press uppercase N to scroll to the - first page. -
- right -
- Scrolls horizontally to the right, to access the data columns situated to - the right of the current set. This command is available when the - >>> symbol appears at the upper right of the screen. Press - uppercase R to scroll horizontally all the way to the right (to - display the final set of data columns). -
The System Overview Screen -
The System Overview screen appears automatically as the - afsmonitor program initializes. This screen displays the - status of as many File Server and Cache Manager processes as can fit in the - current window; scroll down to access additional information. -
The information on this screen is split into File Server information on the - left and Cache Manager information on the right. The header for each - grouping reports two pieces of information: -
-
-
- The number of machines on which the program is monitoring the indicated - process -
- The number of alerts and the number of machines affected by them (an - alertmeans that a statistic has exceeded its threshold or a process - failed to respond to the last probe) -
A list of the machines being monitored follows. If there are any - alerts on a machine, the number of them appears in square brackets to the left - of the hostname. If a process failed to respond to the last probe, the - letters PF (probe failure) appear in square brackets to the left of - the hostname. -
The File Servers Screen -
The File Servers screen displays the values collected at the - most recent probe for File Server statistics. -
A summary line at the top of the screen (just below the standard program - version and screen title blocks) specifies the number of monitored File - Servers, the number of alerts, and the number of machines affected by the - alerts. -
The first column always displays the hostnames of the machines running the - monitored File Servers. -
To the right of the hostname column appear as many columns of statistics as - can fit within the current width of the display screen or window; each - column requires space for 10 characters. The name of the statistic - appears at the top of each column. If the File Server on a machine did - not respond to the most recent probe, a pair of dashes (--) appears - in each column. If a value exceeds its configured threshold, it is - highlighted in reverse video. If a value is too large to fit into the - allotted column width, it overflows into the next row in the same - column. -
The Cache Managers Screen -
The Cache Managers screen displays the values collected at the - most recent probe for Cache Manager statistics. -
A summary line at the top of the screen (just below the standard program - version and screen title blocks) specifies the number of monitored Cache - Managers, the number of alerts, and the number of machines affected by the - alerts. -
The first column always displays the hostnames of the machines running the - monitored Cache Managers. -
To the right of the hostname column appear as many columns of statistics as - can fit within the current width of the display screen or window; each - column requires space for 10 characters. The name of the statistic - appears at the top of each column. If the Cache Manager on a machine - did not respond to the most recent probe, a pair of dashes (--) - appears in each column. If a value exceeds its configured threshold, it - is highlighted in reverse video. If a value is too large to fit into - the allotted column width, it overflows into the next row in the same - column. -
Writing to an Output File -
Include the -output argument to name the file into which the - afsmonitor program writes all of the statistics it collects. - The output file can be useful for tracking performance over long periods of - time, and enables the administrator to apply post-processing techniques that - reveal system trends. The AFS distribution does not include any - post-processing programs. -
The output file is in ASCII format and records the same information as the - File Server and Cache Manager display screens. - Each line in the file uses the following format to record the time at which - the afsmonitor program gathered the indicated statistic from the - Cache Manager (CM) or File Server (FS) running on the - machine called host_name. If a probe failed, the error code - -1 appears in the statistic field. -
time host_name CM|FS statistic - --
If the administrator usually reviews the output file manually, rather than - using it as input to an automated analysis program or script, including the - -detail flag formats the data in a more easily readable - form. -
Examples -
For examples of commands, display screens, and configuration files, see the - section about the afsmonitor program in the IBM AFS - Administration Guide. -
Privilege Required -
None -
Related Information -
afsmonitor Configuration File -
fstrace -
scout -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf060.htm diff -c openafs/doc/html/AdminReference/auarf060.htm:1.1 openafs/doc/html/AdminReference/auarf060.htm:removed *** openafs/doc/html/AdminReference/auarf060.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf060.htm Thu Oct 2 10:12:22 2008 *************** *** 1,267 **** - - -
Administration Reference
-
-
-
backup
- - - - - -Purpose -
Introduction to the backup command suite -
Description -
The commands in the backup command suite are the administrative - interface to the AFS Backup System. There are several categories of - commands in the suite: -
-
-
- Commands to copy data from AFS volumes to tape or a backup data file, and - to restore it to the file system: backup diskrestore, - backup dump, backup volrestore, and backup - volsetrestore -
- Commands to administer the records in the Backup Database: - backup adddump, backup addhost, backup - addvolentry, backup addvolset, backup deldump, - backup deletedump, backup delhost, backup - delvolentry, backup delvolset, backup dumpinfo, - backup listdumps, backup listhosts, backup - listvolsets, backup scantape, backup setexp, and - backup volinfo -
- Commands to write and read tape labels: backup labeltape - and backup readlabel -
- Commands to list and change the status of backup operations and the - machines performing them: (backup) jobs, (backup) - kill, and backup status -
- Commands to enter and leave interactive mode: backup - (interactive) and (backup) quit -
- Commands to check for and repair corruption in the Backup Database: - backup dbverify, backup restoredb, and backup - savedb -
- Commands to obtain help: backup apropos and backup - help -
The backup command interpreter interacts with two other - processes: - - -
-
-
- The Backup Server (buserver) process. It maintains the - Backup Database, which stores most of the administrative information used by - the Backup System. In the standard configuration, the Backup Server - runs on each database server machine in the cell, and uses AFS's - distributed database technology, Ubik, to synchronize its copy of the database - with the copies on the other database server machines. -
- The Backup Tape Coordinator (butc) process. A separate
- instance of the process controls each tape device or backup data file used to
- dump or restore data. The Tape Coordinator runs on a Tape Coordinator
- machine, which is an AFS server or client machine that has one or more tape
- devices attached, or has sufficient disk space to accommodate one or more
- backup data files on its local disk.
-
Each Tape Coordinator must be registered in the Backup Database and in the - /usr/afs/backup/tapeconfig configuration file on the Tape - Coordinator machine's local disk, and information in the two places must - be consistent for proper Backup System performance. The optional - /usr/afs/backup/CFG_device_name for each Tape Coordinator - records information used to automate its operation. -
In addition to the standard command line interface, the backup - command suite provides an interactive interface, which has several - useful features described on the backup (interactive) reference - page. Three of the commands in the suite are available only in - interactive mode: (backup) jobs, (backup) kill, - and (backup) quit. -
Options -
The following options are available on many commands in the - backup suite. The reference page for each command also lists - them, but they are described here in greater detail. - - - -
-
-
- -cell <cell name> -
- Names the cell in which to run the command. It is acceptable to
- abbreviate the cell name to the shortest form that distinguishes it from the
- other entries in the /usr/vice/etc/CellServDB file on the local
- machine. If the -cell argument is omitted, the command
- interpreter determines the name of the local cell by reading the following in
- order:
-
-
-
- The value of the AFSCELL environment variable -
- The local /usr/vice/etc/ThisCell file -
-
Do not combine the -cell and -localauth - options. A command on which the -localauth flag is included - always runs in the local cell (as defined in the server machine's local - /usr/afs/etc/ThisCell file), whereas a command on which the - -cell argument is included runs in the specified foreign - cell. -
The -cell argument is not available on commands issued in - interactive mode. The cell defined when the backup command - interpreter enters interactive mode applies to all commands issued during the - interactive session. - -
- -help -
- Prints a command's online help message on the standard output - stream. Do not combine this flag with any of the command's other - options; when it is provided, the command interpreter ignores all other - options, and only prints the help message. -
- - - -localauth -
- Constructs a server ticket using the server encryption key with the
- highest key version number in the local /usr/afs/etc/KeyFile
- file. The backup command interpreter presents the ticket,
- which never expires, to the Backup Server, Volume Server and Volume Location
- (VL) Server during mutual authentication.
-
Use this flag only when issuing a command on a server machine; client - machines do not usually have a /usr/afs/etc/KeyFile file. - The issuer of a command that includes this flag must be logged on to the - server machine as the local superuser root. The flag is - useful for commands invoked by an unattended application program, such as a - process controlled by the UNIX cron utility or by a cron entry in - the machine's /usr/afs/local/BosConfig file. It is also - useful if an administrator is unable to authenticate to AFS but is logged in - as the local superuser root. -
Do not combine the -cell and -localauth - options. A command on which the -localauth flag is included - always runs in the local cell (as defined in the server machine's local - /usr/afs/etc/ThisCell file), whereas a command on which the - -cell argument is included runs in the specified foreign - cell. -
The -localauth argument is not available on commands issued in - interactive mode. The local identity and AFS tokens with which the - backup command interpreter enters interactive mode apply to all - commands issued during the interactive session. -
- - - -portoffset <TC port offset> -
- Specifies the port offset number of the Tape Coordinator that is to
- execute the backup command. The port offset number uniquely
- identifies a pairing of a Tape Coordinator (butc) process and tape
- device or backup data file.
-
The backup command interpreter and Tape Coordinator process - communicate via a UDP socket, or port. Before issuing a - backup command that involves reading or writing a tape, the backup - operator must start a butc process that controls the appropriate - tape device and listens for requests sent to its port number. If a - Backup System machine has multiple tape devices attached, they can perform - backup operations simultaneously because each device has its own associated - butc process and port offset number. -
The Backup System associates a tape capacity and file mark size with each - port offset (as defined in the tapeconfig file). For a - compressing tape device, the capacity and file mark values differ for - compression and non-compression modes, so the two modes have distinct port - offset numbers. -
The Backup Database can store up to 58,511 port offsets, so the legal - values for this argument are the integers 0 through - 58510. If the issuer omits the argument, it defaults to - 0. (The limit of 58,511 port offsets results from the fact - that UDP socket numbers are identified by a 16-bit integer, and the lowest - socket number used by the Backup System is 7025. The largest number - that a 16-bit integer can represent is 65,535. Subtracting 7,025 yields - 58,510. The addition of port offset 0 (zero) increases the maximum to - 58,511.) -
Although it is possible to define up to 58,511 port offset numbers for a - cell, it is not possible to run 58,511 tape devices simultaneously, due to the - following limits: -
-
-
- The maximum number of dump or restore operations that can run - simultaneously is 64. -
- The maximum number of tape devices that can work together on a restore - operation is 128 (that is the maximum number of values that can be provided - for the -portoffset argument to the backup diskrestore, - backup volrestore, or backup volsetrestore - command). -
-
The Backup System does not reserve UDP sockets. If another - application is already using the Tape Coordinator's socket when it tries - to start, the butc process fails and the following error message - appears at the shell prompt: -
bind: Address already in use - rxi_GetUDPSocket: bind failed - -
-
To issue any backup command that accesses the Backup Database - only, the issuer must be listed in the /usr/afs/etc/UserList file - on every machine where the Backup Server is running. To issue any - backup command that accesses volume data, the issuer must appear in - the UserList file on every Backup Server machine, every Volume - Location (VL) Server machine, and every file server machine that houses - affected volumes. By convention, a common UserList file is - distributed to all database server and file server machines in the - cell. See the chapter on privileged users in the IBM AFS - Administration Guide for more information on this type of - privilege. -
If the -localauth flag is included, the user must instead be - logged on as the local superuser root on the server machine where - the backup command is issued. -
Related Information -
KeyFile -
UserList -
buserver -
butc -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf061.htm diff -c openafs/doc/html/AdminReference/auarf061.htm:1.1 openafs/doc/html/AdminReference/auarf061.htm:removed *** openafs/doc/html/AdminReference/auarf061.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf061.htm Thu Oct 2 10:12:22 2008 *************** *** 1,186 **** - - -
Administration Reference
-
-
-
backup adddump
- - - - - - - - - - - -Purpose -
Defines a dump level in the dump hierarchy -
Synopsis -
backup adddump -dump <dump level name>+ [-expires <expiration date>+] - [-localauth] [-cell <cell name>] [-help] - - backup addd -d <dump level name>+ [-e <expiration date>+] [-l] - [-c <cell name>] [-h] --
Description -
The backup adddump command creates one or more dump levels in - the dump hierarchy stored in the Backup Database, and optionally assigns an - expiration date to each one. All of the dump levels in the Backup - Database collectively constitute the dump hierarchy. -
Use the -expires argument to associate an expiration date with - each dump level. When the Backup System subsequently creates a dump at - the dump level, it uses the specified value to derive the dump's - expiration date, which it records on the label of the tape (or backup data - file). The Backup System refuses to overwrite a tape until after the - latest expiration date of any dump that the tape contains, unless the - backup labeltape command is used to relabel the tape. If a - dump level does not have an expiration date, the Backup System treats dumps - created at the level as expired as soon as it creates them. -
(Note that the Backup System does not automatically remove a dump's - record from the Backup Database when the dump reaches its expiration date, but - only if the tape that contains the dump is recycled or relabeled. To - remove expired and other obsolete dump records, use the backup - deletedump command.) -
Define either an absolute or relative expiration date: -
-
-
- An absolute expiration date defines the month/day/year (and, optionally, - hour and minutes) at which a dump expires. If the expiration date - predates the dump creation time, the Backup System immediately treats the dump - as expired. -
- A relative date defines the number of years, months, or days (or a - combination of the three) after the dump's creation that it - expires. When the Backup System creates a dump at the dump level, it - calculates an actual expiration date by adding the relative date to the start - time of the dump operation. -
Options -
-
-
- -dump -
- Names each dump level to add to the dump hierarchy. Precede full
- dump level names with a slash (for example, /full). Indicate
- an incremental dump level by preceding it with an ordered list of the dump
- levels directly above it in the hierarchy (its parent dump levels); use
- the slash as a separator. The parent dump levels must already
- exist. For example, the dump levels /full and
- /full/incremental1 must exist when the incremental dump level
- /full/incremental1/incremental2 is created.
-
Dump level names can have any number of levels, but cannot exceed 256 - characters in length, including the slashes. The maximum length for any - single level (the text between slashes) is 28 characters, not including the - preceding slash. -
All alphanumeric characters are allowed in dump level names. Do not - use the period (.), however, because it is the separator - between the volume set name and dump level name in the dump name assigned - automatically by the backup dump command. It is best not to - include other metacharacters either; if using them, enclose them in - double quotes (" ") when issuing the backup adddump - command outside interactive mode. -
- -expires -
- Defines the absolute or relative expiration date to associate with each
- dump level named by the -dump argument. Absolute expiration
- dates have the following format:
-
-
[at] {NEVER | mm/dd/yyyy [hh:MM] } - --where the optional word at is followed either by the string - NEVER, which indicates that dumps created at the dump level never - expire, or by a date value with a required portion (mm for month, - dd for day, and yyyy for year) and an optional portion - (hh for hours and MM for minutes). -
Omit the hh:MM portion to use the default of - midnight (00:00 hours), or provide a value in 24-hour format (for - example, 20:30 is 8:30 p.m.). - Valid values for the year range from 1970 to 2037; - higher values are not valid because the latest possible date in the standard - UNIX representation is in February 2038. The command interpreter - automatically reduces later dates to the maximum value. -
Relative expiration dates have the following format: -
[in] [yearsy] [monthsm] [daysd] - -
--
where the optional word in is followed by at least one of a - number of years (maximum 9999) followed by the letter y, - a number of months (maximum 12) followed by the letter - m, or a number of days (maximum 31) followed by the - letter d. If providing more than one of the three, list them - in the indicated order. If the date that results from adding the - relative expiration value to a dump's creation time is later than the - latest possible date in the UNIX time representation, the Backup System - automatically reduces it to that date. -
-Note: A plus sign follows this argument in the command's syntax statement - because it accepts a multiword value which does not need to be enclosed in - double quotes or other delimiters, not because it accepts multiple - dates. Provide only one date (and optionally, time) definition to be - associated with each dump level specified by the -dump - argument. - - -localauth -
- Constructs a server ticket using a key from the local - /usr/afs/etc/KeyFile file. The backup command - interpreter presents it to the Backup Server, Volume Server and VL Server - during mutual authentication. Do not combine this flag with the - -cell argument. For more details, see the introductory - backup reference page. -
- -cell -
- Names the cell in which to run the command. Do not combine this - argument with the -localauth flag. For more details, see the - introductory backup reference page. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Examples -
The following command defines a full dump called /1999 with a - relative expiration date of one year: -
% backup adddump -dump /1999 -expires in 1y - --
The following command defines an incremental dump called - /sunday1/monday1 with a relative expiration date of 13 days: -
% backup adddump -dump /sunday1/monday1 -expires in 13d - --
The following command defines two dump incremental dump levels, - /Monthly/Week1 and /Monthly/Week2. Their parent, - the full dump level /Monthly, must already exist. The - expiration date for both levels is 12:00 a.m. on 1 January - 2000. -
% backup adddump -dump /Monthly/Week1 /Monthly/Week2 -expires at 01/01/2000 - --
Privilege Required -
The issuer must be listed in the /usr/afs/etc/UserList file on - every machine where the Backup Server is running, or must be logged onto a - server machine as the local superuser root if the - -localauth flag is included. -
Related Information -
backup -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf062.htm diff -c openafs/doc/html/AdminReference/auarf062.htm:1.1 openafs/doc/html/AdminReference/auarf062.htm:removed *** openafs/doc/html/AdminReference/auarf062.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf062.htm Thu Oct 2 10:12:22 2008 *************** *** 1,116 **** - - -
Administration Reference
-
-
-
backup addhost
- - - - - - - - - - -Purpose -
Adds a Tape Coordinator entry to the Backup Database -
Synopsis -
backup addhost -tapehost <tape machine name> [-portoffset <TC port offset>] - [-localauth] [-cell <cell name>] [-help] - - backup addh -t <tape machine name> [-p <TC port offset>] - [-l] [-c <cell name>] [-h] --
Description -
The backup addhost command creates a Tape Coordinator entry in - the Backup Database. The entry records -
-
-
- The host name of the Tape Coordinator machine where the Tape Coordinator - (butc) process runs, as specified with the -tapehost - argument. -
- The Tape Coordinator's port offset number, as specified with the - -portoffset argument. An entry for the port offset must also - appear in the /usr/afs/backup/tapeconfig file on the Tape - Coordinator machine, where it is mapped to a UNIX device name (for a tape - device) or pathname (for a backup data file). -
Each Tape Coordinator must have its own port offset number, and the command - fails if a Backup Database entry already exists for the requested port offset - number. To display existing Tape Coordinator entries, use the - backup listhosts command. -
Options -
-
-
- -tapehost -
- Specifies the fully-qualified hostname of the machine for which to create - a Tape Coordinator entry in the Backup Database. The machine must have - an entry in either the cell's naming service (such as the Domain Name - Service) or the host file (/etc/hosts or equivalent) on the machine - where the command is issued. -
- -portoffset -
- Specifies the Tape Coordinator's port offset number. Provide - an integer from the range 0 through 58510, or omit this - argument to use the default value of 0 (zero). The value - must match the port offset number recorded for the same combination of Tape - Coordinator and tape device or file in the - /usr/afs/backup/tapeconfig file on the Tape Coordinator machine - named by the -tapehost argument. -
- -localauth -
- Constructs a server ticket using a key from the local - /usr/afs/etc/KeyFile file. The backup command - interpreter presents it to the Backup Server, Volume Server and VL Server - during mutual authentication. Do not combine this flag with the - -cell argument. For more details, see the introductory - backup reference page. -
- -cell -
- Names the cell in which to run the command. Do not combine this - argument with the -localauth flag. For more details, see the - introductory backup reference page. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Examples -
The following command creates an entry in the Backup Database that assigns - port offset number 4 to a Tape Coordinator running on the machine - backup1.abc.com: -
% backup addhost -tapehost backup1.abc.com -portoffset 4 - --
The following command creates a Backup Database entry that assigns port - offset number 0 to a Tape Coordinator on the machine - backup3.abc.com: -
% backup addhost backup3.abc.com - --
Privilege Required -
The issuer must be listed in the /usr/afs/etc/UserList file on - every machine where the Backup Server is running, or must be logged onto a - server machine as the local superuser root if the - -localauth flag is included. -
Related Information -
backup -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf063.htm diff -c openafs/doc/html/AdminReference/auarf063.htm:1.1 openafs/doc/html/AdminReference/auarf063.htm:removed *** openafs/doc/html/AdminReference/auarf063.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf063.htm Thu Oct 2 10:12:22 2008 *************** *** 1,189 **** - - -
Administration Reference
-
-
-
backup addvolentry
- - - - - - - - - - - - - - -Purpose -
Defines a volume entry in a volume set -
Synopsis -
backup addvolentry -name <volume set name> -server <machine name> - -partition <partition name> - -volumes <volume name (regular expression)> - [-localauth] [-cell <cell name>] [-help] - - backup addvole -n <volume set name> -s <machine name> -p <partition name> - -v <volume name (regular expression)> - [-l] [-c <cell name>] [-h] --
Description -
The backup addvolentry command adds a volume entry definition to - the existing volume set named by the -name argument. A - volume entry definition can match one or more volumes, depending on the - combination of the -server, -partition, and - -volumes arguments. -
For the -server and -partition arguments, provide - either -
-
-
- The name of one machine or partition -
- The metacharacter expression .* (period and asterisk), - which matches every machine name or partition name in the Volume Location - Database (VLDB). -
For the -volumes argument, specify a combination of alphanumeric - characters and one or more metacharacters to wildcard part or all of the - volume name. The Options section lists the acceptable - metacharacters. -
Cautions -
It is best to issue this command in interactive mode. If issuing it - at the shell prompt, enclose any strings containing metacharacters in double - quotes, or escape the metacharacters with other delimiters, to prevent the - shell from interpreting them. Adding volume entries to a temporary - volume set is possible only within the interactive session in which the volume - set was created. -
Options -
-
-
- -name -
- Names the volume set to which to add this volume entry definition. - The volume set must already exist (use the backup addvolset command - to create it). -
- -server -
- Defines the set of one or more file server machines that house the volumes - in the volume entry. Provide either one fully-qualified hostname (such - as fs1.abc.com) or the metacharacter expression - .* (period and asterisk), which matches all machine names in - the VLDB. -
- -partition -
- Defines the set of one or more partitions that house the volumes in the - volume entry. Provide either one complete partition name (such as - /vicepa) or the metacharacter expression .* - (period and asterisk), which matches all partition names. -
- -volumes -
- Defines the set of one or more volumes included in the volume
- entry. Specify the volumes by name, by using any combination of regular
- alphanumeric characters and one or more of the following metacharacter
- expressions:
-
-
-
-
-
- . -
- The period matches any single character. -
- * -
- The asterisk matches zero or more instances of the preceding - character. Combine it with any other alphanumeric character or - metacharacter. -
- [ ] -
- Square brackets around a list of characters match a single instance of any - of the characters, but no other characters; for example, [abc] - matches a single a or b or c, but not - d or A. This expression can be combined with the - asterisk. -
- ^ -
- The caret, when used as the first character in a square-bracketed set, - designates a match with any single character except the characters - that follow it; for example, [^a] matches any single character - except lowercase a. This expression can be combined with the - asterisk. -
- \ -
- A backslash preceding any of the metacharacters in this list makes it - match its literal value only. For example, the expression - \. (backslash and period) matches a single period, - \* a single asterisk, and \\ a single backslash. - Such expressions can be combined with the asterisk (for example, - \.* matches any number of periods). -
-
Perhaps the most common metacharacter expression is the period followed by - an asterisk (.*). This expression matches any string - of any length, because the period matches any character and the asterisk means - any number of that character. As mentioned, it is the only acceptable - metacharacter expression for the -server and -partition - arguments. In a volume definition it can stand alone (in which case it - matches every volume listed in the VLDB), or can combine with regular - characters. The following example matches any volume name that begins - with the string user and ends with backup: -
user.*backup - -
- - -localauth -
- Constructs a server ticket using a key from the local - /usr/afs/etc/KeyFile file. The backup command - interpreter presents it to the Backup Server, Volume Server and VL Server - during mutual authentication. Do not combine this flag with the - -cell argument. For more details, see the introductory - backup reference page. -
- -cell -
- Names the cell in which to run the command. Do not combine this - argument with the -localauth flag. For more details, see the - introductory backup reference page. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Examples -
The following command adds a volume entry to the volume set called - sys. The entry matches all volumes on any machine or - partition whose names begin with the string sun4x_56 followed by a - period: -
backup> addvolentry sys .* .* sun4x_56\..* - --
The following command adds a volume entry to the volume set called - fs2, to match all volumes on the /vicepb partition of - file server machine fs2.abc.com. Because it is - issued at the shell prompt, double quotes surround the metacharacters in the - -volumes argument. (The command is shown here on two lines - only for legibility reasons.) -
% backup addvolentry -name fs2 -server fs2.abc.com \ - -partition /vicepb -volumes ".*" - --
The chapter in the IBM AFS Administration Guide about - configuring the AFS Backup System presents additional examples as well as - advice on grouping volumes. -
Privilege Required -
The issuer must be listed in the /usr/afs/etc/UserList file on - every machine where the Backup Server is running, or must be logged onto a - server machine as the local superuser root if the - -localauth flag is included. -
Related Information -
backup -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf064.htm diff -c openafs/doc/html/AdminReference/auarf064.htm:1.1 openafs/doc/html/AdminReference/auarf064.htm:removed *** openafs/doc/html/AdminReference/auarf064.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf064.htm Thu Oct 2 10:12:22 2008 *************** *** 1,109 **** - - -
Administration Reference
-
-
-
backup addvolset
- - - - - - -Purpose -
Creates a new (empty) volume set -
Synopsis -
backup addvolset -name <volume set name> [-temporary] - [-localauth] [-cell <cell name>] [-help] - - backup addvols -n <volume set name> [-t] [-l] [-c <cell name>] [-h] --
Description -
The backup addvolset command creates a new volume set, by - default adding it to the Backup Database. It is best that the volume - set's name indicate the volume set's contents; for example, - define the volume entries in the user volume set to match all user - volumes. The volume set name must be unique within the Backup Database - of the local cell. -
After issuing this command, issue the backup addvolentry command - to define the volume entries in the volume set. -
Sometimes it is convenient to create volume sets without recording them - permanently in the Backup Database, for example when using the backup - volsetrestore command to restore a group of volumes that were not - necessarily backed up together. To create a temporary volume - set, include the -temporary flag. A temporary volume set - exists only during the lifetime of the current interactive session, so the - flag is effective only when used during an interactive session (opened by - issuing the backup interactive command). If it is included - when the command is issued at the regular command shell prompt, the command - appears to succeed, but the volume set is not created. As noted, a - temporary volume set ceases to exist when the current interactive session - ends, or use the backup delvolset command to delete it before - that. -
One advantage of temporary volume sets is that the backup - addvolset command, and any backup addvolentry commands - subsequently used to add volume entries to it, complete more quickly than for - regular volume sets, because no records are created in the Backup - Database. -
Options -
-
-
- -name -
- Names the new volume set. The name can include up to 31 of any - character other than the period. Avoid other metacharacters as - well. -
- -temporary -
- Creates a volume set that exists only within the context of the current - interactive session. It is not added to the Backup Database. -
- -localauth -
- Constructs a server ticket using a key from the local - /usr/afs/etc/KeyFile file. The backup command - interpreter presents it to the Backup Server, Volume Server and VL Server - during mutual authentication. Do not combine this flag with the - -cell argument. For more details, see the introductory - backup reference page. -
- -cell -
- Names the cell in which to run the command. Do not combine this - argument with the -localauth flag. For more details, see the - introductory backup reference page. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Examples -
The following command creates a volume set called sys: -
% backup addvolset sys - --
Privilege Required -
The issuer must be listed in the /usr/afs/etc/UserList file on - every machine where the Backup Server is running, or must be logged onto a - server machine as the local superuser root if the - -localauth flag is included. -
Related Information -
backup -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf065.htm diff -c openafs/doc/html/AdminReference/auarf065.htm:1.1 openafs/doc/html/AdminReference/auarf065.htm:removed *** openafs/doc/html/AdminReference/auarf065.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf065.htm Thu Oct 2 10:12:22 2008 *************** *** 1,73 **** - - -
Administration Reference
-
-
-
backup apropos
- - - -Purpose -
Displays each help entry containing a keyword string -
Synopsis -
backup apropos -topic <help string> [-help] - - backup ap -t <help string> [-h] --
Description -
The backup apropos command displays the first line of the online - help entry for any backup command that has in its name or short - description the string specified by the -topic argument. -
To display the syntax for a command, use the backup help - command. -
Options -
-
-
- -topic -
- Specifies the keyword string to match, in lowercase letters only. - If the string is more than a single word, surround it with double quotes - (" ") or other delimiters. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Output -
The first line of a command's online help entry names it and briefly - describes its function. This command displays the first line for any - backup command where the string specified with the - -topic argument is part of the command name or first line. -
Examples -
The following example lists all backup commands that include the - word tape in their names or short descriptions: -
% backup apropos tape - labeltape: label a tape - readlabel: read the label on tape - scantape: dump information recovery from tape - status: get tape coordinator status - --
Privilege Required -
None -
Related Information -
backup -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf066.htm diff -c openafs/doc/html/AdminReference/auarf066.htm:1.1 openafs/doc/html/AdminReference/auarf066.htm:removed *** openafs/doc/html/AdminReference/auarf066.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf066.htm Thu Oct 2 10:12:22 2008 *************** *** 1,124 **** - - -
Administration Reference
-
-
-
backup dbverify
- - - -Purpose -
Checks the integrity of the Backup Database -
Synopsis -
backup dbverify [-detail] [-localauth] [-cell <cell name>] [-help] - - backup db [-d] [-l] [-c <cell name>] [-h] --
Description -
The backup dbverify command checks the integrity of the Backup - Database. The command's output indicates whether the Backup - Database is damaged (data is corrupted) or not. If the Backup Database - is undamaged, it is safe to continue using it. If it is corrupted, - discontinue any backup operations until it is repaired. -
Cautions -
While this command runs, no other backup operation can access the Backup - Database; the other commands do not run until this command - completes. Avoid issuing this command when other backup operations are - likely to run. The backup savedb command repairs some types - of corruption. -
Options -
-
-
- -detail -
- Reports the number of orphaned blocks found, any inconsistencies, and the - name of the server machine running the Backup Server that is checking its copy - of the database. -
- -localauth -
- Constructs a server ticket using a key from the local - /usr/afs/etc/KeyFile file. The backup command - interpreter presents it to the Backup Server, Volume Server and VL Server - during mutual authentication. Do not combine this flag with the - -cell argument. For more details, see the introductory - backup reference page. -
- -cell -
- Names the cell in which to run the command. Do not combine this - argument with the -localauth flag. For more details, see the - introductory backup reference page. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Output -
The command displays one of the following two messages: -
-
-
- Database OK -
- The database is undamaged and can be used. -
- Database not OK -
- The database is damaged. You can use the backup savedb - command to repair many kinds of corruption as it creates a backup copy. - For more detailed instructions, see the IBM AFS Administration - Guide chapter about performing backup operations. -
The -detail flag provides additional information: -
-
-
- The number of orphan blocks found. These are ranges of - memory that the Backup Server preallocated in the database but cannot - use. Orphan blocks do not interfere with database access, but do waste - disk space. To free the unusable space, dump the database to tape by - using the backup savedb command, and then restore it by using the - backup restoredb command. -
- Any inconsistencies in the database, such as invalid hostnames for Tape - Coordinator machines. -
- The name of the database server machine on which the Backup Database was - checked, designated as the Database checker. For a detailed - trace of the verification operation, see the - /usr/afs/logs/BackupLog file on the indicated machine. You - can use the bos getlog command to display it. -
Examples -
The following command confirms that the Backup Database is undamaged: -
% backup dbverify - Database OK - --
The following command confirms that the Backup Database is undamaged and - that it has no orphan blocks or invalid Tape Coordinator entries. The - Backup Server running on the machine db1.abc.com - checked its copy of the Database. -
% backup dbverify -detail - Database OK - Orphan blocks 0 - Database checker was db1.abc.com - --
Privilege Required -
The issuer must be listed in the /usr/afs/etc/UserList file on - every machine where the Backup Server is running, or must be logged onto a - server machine as the local superuser root if the - -localauth flag is included. -
Related Information -
backup -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf067.htm diff -c openafs/doc/html/AdminReference/auarf067.htm:1.1 openafs/doc/html/AdminReference/auarf067.htm:removed *** openafs/doc/html/AdminReference/auarf067.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf067.htm Thu Oct 2 10:12:22 2008 *************** *** 1,82 **** - - -
Administration Reference
-
-
-
backup deldump
- - - - - - - - -Purpose -
Deletes a dump level from the Backup Database -
Synopsis -
backup deldump -dump <dump level name> [-localauth] - [-cell <cell name>] [-help] - - backup deld -d <dump level name> [-l] [-c <cell name>] [-h] --
Description -
The backup deldump command deletes the indicated dump level and - all of its child dump levels from the dump hierarchy in the Backup - Database. Use the backup listdumps command to display the - dump hierarchy. -
Options -
-
-
- -dump -
- Specifies the complete pathname of the dump level to delete. -
- -localauth -
- Constructs a server ticket using a key from the local - /usr/afs/etc/KeyFile file. The backup command - interpreter presents it to the Backup Server, Volume Server and VL Server - during mutual authentication. Do not combine this flag with the - -cell argument. For more details, see the introductory - backup reference page. -
- -cell -
- Names the cell in which to run the command. Do not combine this - argument with the -localauth flag. For more details, see the - introductory backup reference page. -
- -help -
- Prints the online help for this command. All other valid options - are ignored. -
Examples -
The following command deletes the dump level /sunday1/monday1 - from the dump hierarchy, along with any of its child dump levels. -
% backup deldump /sunday1/monday1 - --
Privilege Required -
The issuer must be listed in the /usr/afs/etc/UserList file on - every machine where the Backup Server is running, or must be logged onto a - server machine as the local superuser root if the - -localauth flag is included. -
Related Information -
backup -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf068.htm diff -c openafs/doc/html/AdminReference/auarf068.htm:1.1 openafs/doc/html/AdminReference/auarf068.htm:removed *** openafs/doc/html/AdminReference/auarf068.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf068.htm Thu Oct 2 10:12:22 2008 *************** *** 1,183 **** - - -