Administration Guide

How to Use This Document +

Document Organization +

A Broad Overview of AFS +

An Overview of AFS Administration
+

More Detailed Discussions of Some Basic Concepts + +

Networks +

Distributed File Systems +

Servers and Clients +

Cells +

The Uniform Namespace and Transparent Access +

Volumes +

Mount Points +

Replication +

Caching and Callbacks +

AFS Server Processes and the Cache Manager + +

The File Server +

The Basic OverSeer Server +

The Authentication Server +

The Protection Server +

The Volume Server +

The Volume Location (VL) Server +

The Update Server +

The Backup Server +

The Salvager +

The Network Time Protocol Daemon +

The Cache Manager +

Issues in Cell Configuration and Administration
+

Differences between AFS and UNIX: A Summary + +

Differences in File and Directory Protection +

Differences in Authentication +

Differences in the Semantics of Standard UNIX Commands +

The AFS version of the fsck Command +

Creating Hard Links +

AFS Implements Save on Close +

Setuid Programs +

Choosing a Cell Name + +

How to Set the Cell Name +

Why Choosing the Appropriate Cell Name is Important +

Participating in the AFS Global Namespace + +

What the Global Namespace Looks Like +

Making Your Cell Visible to Others +

Making Other Cells Visible in Your Cell +

Granting and Denying Foreign Users Access to Your Cell +

Configuring Your AFS Filespace + +

The Top /afs Level +

The Second (Cellname) Level +

The Third Level +

Creating Volumes to Simplify Administration + +

Assigning Volume Names +

When to Replicate Volumes +

The Default Quota and ACL on a New Volume +

Configuring Server Machines + +

Replicating the AFS Administrative Databases +

AFS Files on the Local Disk +

Configuring Partitions to Store AFS Data +

Monitoring, Rebooting and Automatic Process Restarts +

Configuring Client Machines + +

Configuring the Local Disk +

Enabling Access to Foreign Cells +

Using the @sys Variable in Pathnames +

Setting Server Preferences +

Configuring AFS User Accounts + +

Choosing Usernames and Naming Other Account Components +

Grouping Home Directories +

Making a Backup Version of User Volumes Available +

Creating Standard Files in New AFS Accounts +

Using AFS Protection Groups + +

The Three System Groups +

The Two Types of User-Defined Groups +

Identifying AFS Tokens by PAG +

Using an AFS-modified login Utility +

Using Two-Step Login and Authentication +

Obtaining, Displaying, and Discarding Tokens +

Setting Default Token Lifetimes for Users +

Changing Passwords +

Imposing Restrictions on Passwords and Authentication Attempts +

Support for Kerberos Authentication +

Security and Authorization in AFS + +

Some Important Security Features +

Three Types of Privilege +

Authorization Checking versus Authentication +

Improving Security in Your Cell +

A More Detailed Look at Mutual Authentication +

Backing Up AFS Data + +

Backup Volumes +

The AFS Backup System +

Using UNIX Remote Services in the AFS Environment +

Accessing AFS through NFS +

Administering Server Machines
+

Local Disk Files on a Server Machine + +

Binaries in the /usr/afs/bin Directory +

Common Configuration Files in the /usr/afs/etc Directory +

Local Configuration Files in the /usr/afs/local Directory +

Replicated Database Files in the /usr/afs/db Directory +

Log Files in the /usr/afs/logs Directory +

Volume Headers on Server Partitions +

The Four Roles for File Server Machines + +

Simple File Server Machines +

Database Server Machines +

Binary Distribution Machines +

The System Control Machine +

To locate database server machines +

To locate the system control machine +

To locate the binary distribution machine for a system type +

Interpreting the Output from the bos status Command +

Administering Database Server Machines + +

Replicating the AFS Administrative Databases +

Backing Up and Restoring the Administrative Databases +

To back up the administrative databases +

To restore an administrative database +

Installing Server Process Software + +

Installing New Binaries +

To install new server binaries +

Reverting to the Previous Version of Binaries +

To revert to the previous version of binaries +

Displaying Binary Version Dates +

To display binary version dates +

Removing Obsolete Binary Files +

To remove obsolete binaries +

Displaying A Binary File's Build Level +

To display an AFS binary's build level +

Maintaining the Server CellServDB File + +

Distributing the Server CellServDB File +

To display a cell's database server machines +

To add a database server machine to the CellServDB file +

To remove a database server machine from the CellServDB file +

Managing Authentication and Authorization Requirements + +

Authentication versus Authorization +

Controlling Authorization Checking on a Server Machine +

To disable authorization checking on a server machine +

To enable authorization checking on a server machine +

Bypassing Mutual Authentication for an Individual Command +

To bypass mutual authentication for bos, kas, pts, and vos commands +

To bypass mutual authentication for fs commands +

Adding or Removing Disks and Partitions + +

To add and mount a new disk to house AFS volumes +

To unmount and remove a disk housing AFS volumes +

Managing Server IP Addresses and VLDB Server Entries + +

To create or edit the server NetInfo file +

To create or edit the server NetRestrict file +

To display all server entries from the VLDB +

To remove obsolete server entries from the VLDB +

To change a server machine's IP addresses +

Rebooting a Server Machine + +

To reboot a file server machine from its console +

To reboot a file server machine remotely +

Monitoring and Controlling Server Processes
+

Brief Descriptions of the AFS Server Processes + +

The bosserver Process: the Basic OverSeer Server +

The buserver Process: the Backup Server +

The fs Collection of Processes: the File Server, Volume Server and Salvager +

The kaserver Process: the Authentication Server +

The ptserver Process: the Protection Server +

The runntp Process +

The upserver and upclient Processes: the Update Server +

The vlserver Process: the Volume Location Server +

Controlling and Checking Process Status + +

The Information in the BosConfig File +

How the BOS Server Uses the Information in the BosConfig File +

About Starting and Stopping the Database Server Processes +

About Starting and Stopping the Update Server +

Displaying Process Status and Information from the BosConfig File + +

To display the status of server processes and their BosConfig entries +

Creating and Removing Processes + +

To create and start a new process +

To stop a process and remove it from the BosConfig file +

Stopping and Starting Processes Permanently + +

To stop a process by changing its status to NotRun +

To start processes by changing their status flags to Run +

Stopping and Starting Processes Temporarily + +

To stop processes temporarily +

To start all stopped processes that have status flag Run in the BosConfig file +

To start specific processes +

Stopping and Immediately Restarting Processes + +

To stop and restart all processes including the BOS Server +

To stop and immediately restart all processes except the BOS Server +

To stop and immediately restart specific processes +

Setting the BOS Server's Restart Times + +

To display the BOS Server restart times +

To set the general or binary restart time +

Displaying Server Process Log Files + +

To examine a server process log file +

Managing Volumes
+

The Three Types of Volumes +

About Volumes + +

How Volumes Improve AFS Efficiency +

Volume Information in the VLDB +

The Information in Volume Headers +

Keeping the VLDB and Volume Headers Synchronized +

About Mounting Volumes +

About Volume Names +

Creating Read/write Volumes + +

To create (and mount) a read/write volume +

About Clones and Cloning +

Replicating Volumes (Creating Read-only Volumes) + +

Using Read-only Volumes Effectively +

Replication Scenarios +

To replicate a read/write volume (create a read-only volume) +

Creating Backup Volumes + +

Backing Up Multiple Volumes at Once +

Automating Creation of Backup Volumes +

Making the Contents of Backup Volumes Available to Users +

To create and mount a backup volume +

To create multiple backup volumes at once +

Mounting Volumes + +

The Rules of Mount Point Traversal +

The Three Types of Mount Points +

Creating a mount point in a foreign cell +

To display a mount point +

To create a regular or read/write mount point +

To create a cellular mount point +

To remove a mount point +

Displaying Information About Volumes + +

Displaying VLDB Entries +

To display VLDB entries +

Displaying Volume Headers +

To display volume headers +

Displaying One Volume's VLDB Entry and Volume Header +

To display one volume's VLDB entry and volume header +

Displaying the Name or Location of the Volume that Contains a File +

Moving Volumes + +

To move a read/write volume +

Synchronizing the VLDB and Volume Headers + +

To synchronize the VLDB with volume headers +

Salvaging Volumes + +

To salvage volumes +

Setting and Displaying Volume Quota and Current Size + +

To set quota for a single volume +

To set maximum quota on one or more volumes +

To display percent quota used +

To display quota, current size, and other information +

To display quota, current size, and more partition information +

Removing Volumes and their Mount Points + +

Other Removal Commands +

To remove a volume and unmount it +

Dumping and Restoring Volumes + +

About Dumping Volumes +

To dump a volume +

About Restoring Volumes +

To restore a dump into a new volume and mount it +

To restore a dump file, overwriting an existing volume +

Renaming Volumes + +

To rename a volume +

Unlocking and Locking VLDB Entries + +

To lock a VLDB entry +

To unlock a single VLDB entry +

To unlock multiple VLDB entries +

Configuring the AFS Backup System
+

Introduction to Backup System Features + +

Volume Sets and Volume Entries +

Dumps and Dump Sets +

Dump Hierarchies, Dump Levels and Expiration Dates +

Dump Names and Tape Names +

Tape Labels, Dump Labels, and EOF Markers +

Tape Coordinator Machines, Port Offsets, and Backup Data Files +

The Backup Database and Backup Server Process +

Interfaces to the Backup System +

Overview of Backup System Configuration +

Configuring the tapeconfig File + +

To run the fms command on a noncompressing tape device +

Granting Administrative Privilege to Backup Operators +

Configuring Tape Coordinator Machines and Tape Devices + +

To configure a Tape Coordinator machine +

To configure an additional Tape Coordinator on an existing Tape Coordinator machine +

To unconfigure a Tape Coordinator +

To display the list of configured Tape Coordinators +

Defining and Displaying Volume Sets and Volume Entries + +

To create a volume set +

To add a volume entry to a volume set +

To display volume sets and volume entries +

To delete a volume set +

To delete a volume entry from a volume set +

Defining and Displaying the Dump Hierarchy + +

Creating a Tape Recycling Schedule +

Archiving Tapes +

Defining Expiration Dates +

To add a dump level to the dump hierarchy +

To change a dump level's expiration date +

To delete a dump level from the dump hierarchy +

To display the dump hierarchy +

Writing and Reading Tape Labels + +

Recording a Name on the Label +

Recording a Capacity on the Label +

To label a tape +

To read the label on a tape +

Automating and Increasing the Efficiency of the Backup Process + +

Creating a Device Configuration File +

Invoking a Device's Tape Mounting and Unmounting Routines +

Eliminating the Search or Prompt for the Initial Tape +

Enabling Default Responses to Error Conditions +

Eliminating the AFS Tape Name Check +

Setting the Memory Buffer Size to Promote Tape Streaming +

Dumping Data to a Backup Data File +

To configure a backup data file +

Backing Up and Restoring AFS Data
+

Using the Backup System's Interfaces + +

Performing Backup Operations as the Local Superuser Root or in a Foreign Cell +

Using Interactive and Regular Command Mode +

To enter interactive mode +

To exit interactive mode +

To display pending or running jobs in interactive mode +

To cancel operations in interactive mode +

Starting and Stopping the Tape Coordinator Process +

To start a Tape Coordinator process +

To stop a Tape Coordinator process +

To check the status of a Tape Coordinator process +

Backing Up Data + +

Making Backup Operations More Efficient +

How Your Configuration Choices Influence the Dump Process +

Appending Dumps to an Existing Dump Set +

Scheduling Dumps +

To create a dump +

Displaying Backup Dump Records + +

To display dump records +

To display a volume's dump history +

To scan the contents of a tape +

Restoring and Recovering Data + +

Making Restore Operations More Efficient +

Using the backup volrestore Command +

To restore volumes with the backup volrestore command +

Using the backup diskrestore Command +

To restore a partition with the backup diskrestore command +

Using the backup volsetrestore Command +

To restore a group of volumes with the backup volsetrestore command +

Maintaining the Backup Database + +

Backing Up and Restoring the Backup Database +

Checking for and Repairing Corruption in the Backup Database +

To verify the integrity of the Backup Database +

To repair corruption in the Backup Database +

Removing Obsolete Records from the Backup Database +

To delete dump records from the Backup Database +

Monitoring and Auditing AFS Performance
+

Using the -basename argument to Specify a Domain Name +

Using the scout Program + +

System Requirements +

The Layout of the scout Display +

Highlighting Significant Statistics +

Resizing the scout Display +

To start the scout program +

To stop the scout program +

Example Commands and Displays +

Using the fstrace Command Suite + +

About the fstrace Command Suite +

Requirements for Using the fstrace Command Suite +

Using fstrace Commands Effectively +

Activating the Trace Log +

To configure the trace log +

To set the event set +

Displaying the State of a Trace Log or Event Set +

To display the state of an event set +

To display the log size +

Dumping and Clearing the Trace Log +

To dump the contents of a trace log +

To clear the contents of a trace log +

Examples of fstrace Commands +

Using the afsmonitor Program + +

Requirements for running the afsmonitor program +

The afsmonitor Output Screens +

The System Overview Screen +

The File Servers Screen +

The Cache Managers Screen +

Configuring the afsmonitor Program +

Writing afsmonitor Statistics to a File +

To start the afsmonitor Program +

To stop the afsmonitor program +

The xstat Data Collection Facility + +

The libxstat Libraries +

Example xstat Commands +

Auditing AFS Events on AIX File Servers + +

Configuring AFS Auditing on AIX File Servers +

To enable AFS auditing +

To disable AFS auditing +

Managing Server Encryption Keys
+

Keys and Mutual Authentication: A Review +

About Server Encryption Keys + +

Maintaining AFS Server Encryption Keys +

Displaying Server Encryption Keys + +

To display the KeyFile file +

To display the afs key from the Authentication Database +

Adding Server Encryption Keys + +

To add a new server encryption key +

Removing Server Encryption Keys + +

To remove a key from the KeyFile file +

Handling Server Encryption Key Emergencies + +

Prevent Mutual Authentication +

Disable Authorization Checking by Hand +

Work Quickly on Each Machine +

Work at the Console +

Change Individual KeyFile Files +

Two Component Procedures +

To create a new server encryption key in emergencies +

Administering Client Machines and the Cache Manager
+

Overview of Cache Manager Customization +

Configuration and Cache-Related Files on the Local Disk + +

Configuration Files in the /usr/vice/etc Directory +

Cache-Related Files +

Determining the Cache Type, Size, and Location + +

Choosing the Cache Size +

Displaying and Setting the Cache Size and Location +

To display the cache size set at reboot +

To display the current cache size +

To edit the cacheinfo file +

To change the disk cache size without rebooting +

To reset the disk cache size to the default without rebooting +

How the Cache Manager Chooses Data to Discard +

Setting Other Cache Parameters with the afsd program + +

Setting Cache Configuration Parameters +

Configuring a Disk Cache +

Controlling Memory Cache Configuration +

Maintaining Knowledge of Database Server Machines + +

How Clients Use the List of Database Server Machines +

The Format of the CellServDB file +

Maintaining the Client CellServDB File +

To display the /usr/vice/etc/CellServDB file +

To display the list of database server machines in kernel memory +

To change the list of a cell's database server machines in kernel memory +

Determining if a Client Can Run Setuid Programs + +

To determine a cell's setuid status +

To change a cell's setuid status +

Setting the File Server Probe Interval + +

To set a client's file server probe interval +

Setting a Client Machine's Cell Membership + +

To display a client machine's cell membership +

To set a client machine's cell membership +

Forcing the Update of Cached Data + +

To flush certain files or directories +

To flush all data from a volume +

To force the Cache Manager to notice other volume changes +

To flush one or more mount points +

Maintaining Server Preference Ranks + +

How the Cache Manager Sets Default Ranks +

How the Cache Manager Uses Preference Ranks +

Displaying and Setting Preference Ranks +

To display server preference ranks +

To set server preference ranks +

Managing Multihomed Client Machines + +

To create or edit the client NetInfo file +

To create or edit the client NetRestrict file +

To display the list of addresses from kernel memory +

To set the list of addresses in kernel memory +

Controlling the Display of Warning and Informational Messages + +

To control the display of warning and status messages +

Displaying and Setting the System Type Name + +

To display the system type name +

To change the system type name +

Enabling Asynchronous Writes + +

To set the default store asynchrony +

To set the store asynchrony for one or more files +

To display the default store asynchrony +

To display the store asynchrony for one or more files +

Configuring Client Machines with the package Program
+

Using Package on File Server Machines +

Using the package Program + +

Package Overview + +

Preparing Prototype Files +

Compiling Prototype Files +

Preparing Clients +

The package Directory Structure + +

The src directory +

The lib directory +

The etc directory +

Example Prototype and Library Files + +

An Example Prototype File +

Example Library File +

Package Configuration File Instruction Syntax + +

Local Files versus Symbolic Links +

Defining a Directory +

Defining a File +

Defining a Symbolic Link +

Defining a Block Special Device +

Defining a Character Special Device +

Defining a Socket +

Constructing Prototype and Library Files + +

To construct a prototype file and its component library files +

The Package Makefile File + +

Overview +

The CONFIG Section +

The BASE_LIBS Section +

The MACHINE_LIBS Section +

The LIBS Section +

The .SUFFIXES Section +

The Makefile Instructions Section +

Modifying the Makefile + +

Adding a New Prototype File +

Adding a New System Type +

Adding New Library Files +

Compiling Prototype Files + +

To compile prototype files +

Modifying Client Machines + +

To prepare a client machine to run the package program +

Running the package program + +

To invoke the package program by rebooting +

To invoke the package program directly (without rebooting) +

Creating and Deleting User Accounts with the uss Command Suite
+

The Components of an AFS User Account +

Overview of the uss Command Suite + +

Privilege Requirements for the uss Commands +

Avoiding and Recovering from Errors and Interrupted Operations +

Creating Local Password File Entries with uss + +

Assigning AFS and UNIX UIDs that Match +

Specifying Passwords in the Local Password File +

Creating a Common Source Password File +

Converting Existing UNIX Accounts with uss + +

Making UNIX and AFS UIDs Match +

Setting the Password Field Appropriately +

Moving Local Files into AFS +

Constructing a uss Template File + +

Creating the Three Types of User Accounts +

Using Constants and Variables in the Template File +

Where to Place Template Files +

Some General Rules for Constructing a Template +

About Creating Local Disk Directories and Files +

Example uss Templates +

Evenly Distributing User Home Directories with the G Instruction +

Creating a Volume with the V Instruction +

Creating a Directory with the D Instruction +

Creating a File from a Prototype with the F Instruction +

Creating One-Line Files with the E Instruction +

Creating Links with the L and S Instructions +

Increasing Account Security with the A Instruction +

Executing Commands with the X Instruction +

Creating Individual Accounts with the uss add Command + +

To create an AFS account with the uss add command +

Deleting Individual Accounts with the uss delete Command + +

To delete an AFS account +

Creating and Deleting Multiple Accounts with the uss bulk Command + +

Constructing a Bulk Input File +

Example Bulk Input File Instructions +

To create and delete multiple AFS user accounts +

Administering User Accounts
+

The Components of an AFS User Account +

Creating Local Password File Entries + +

Assigning AFS and UNIX UIDs that Match +

Specifying Passwords in the Local Password File +

Converting Existing UNIX Accounts + +

Making UNIX and AFS UIDs Match +

Setting the Password Field Appropriately +

Moving Local Files into AFS +

Creating AFS User Accounts + +

To create one user account with individual commands +

Improving Password and Authentication Security + +

To limit the number of consecutive failed authentication attempts +

To unlock a locked user account +

To set password lifetime +

To prohibit reuse of passwords +

Changing AFS Passwords + +

To change an AFS password +

Displaying and Setting the Quota on User Volumes +

Changing Usernames + +

To change a username +

Removing a User Account + +

To remove a user account +

Administering the Protection Database
+

Displaying Information from the Protection Database + +

About the Protection Database + +

The System Groups +

To display a Protection Database entry +

To display group membership +

To list the groups that a user or group owns +

To display all Protection Database entries +

Creating User and Machine Entries + +

To create machine entries in the Protection Database +

Creating Groups + +

Using Groups Effectively +

To create groups +

To create a self-owned group +

Using Prefix-Less Groups +

Adding and Removing Group Members + +

To add users and machines to groups +

To remove users and machines from groups +

Deleting Protection Database Entries + +

To delete Protection Database entries +

Changing a Group's Owner + +

To change a group's owner +

Changing a Protection Database Entry's Name + +

To change the name of a machine or group entry +

Setting Group-Creation Quota + +

To set group-creation quota +

Setting the Privacy Flags on Database Entries + +

To set a Protection Database entry's privacy flags +

Displaying and Setting the AFS UID and GID Counters + +

To display the AFS ID counters +

To set the AFS ID counters +

Managing Access Control Lists
+

Differences Between UFS and AFS Data Protection +

Protecting Data in AFS + +

The AFS ACL Permissions +

Using Normal and Negative Permissions +

Using Groups on ACLs +

Displaying ACLs + +

To display an ACL +

Setting ACL Entries + +

To add, remove, or edit normal ACL permissions +

To add, remove, or edit negative ACL permissions +

Completely Replacing an ACL + +

To replace an ACL completely +

Copying ACLs Between Directories + +

To copy an ACL between directories +

Removing Obsolete AFS IDs from ACLs + +

To clean obsolete AFS IDs from an ACL +

How AFS Interprets the UNIX Mode Bits +

Managing Administrative Privilege
+

An Overview of Administrative Privilege + +

The Reason for Separate Privileges +

Administering the system:administrators Group + +

To display the members of the system:administrators group +

To add users to the system:administrators group +

To remove users from the system:administrators group +

Granting Privilege for kas Commands: the ADMIN Flag + +

To check if the ADMIN flag is set +

To set or remove the ADMIN flag +

Administering the UserList File + +

To display the users in the UserList file +

To add users to the UserList file +

To remove users from the UserList file +

Appendix A. Managing the NFS/AFS Translator
+

Enabling Unauthenticated or Authenticated AFS Access +

Overview + +

Setting the AFSSERVER and AFSCONF Environment Variables +

Delayed Writes for Files Saved on NFS Client Machines +

Configuring NFS/AFS Translator Machines + +

Loading NFS and AFS Kernel Extensions +

Configuring the Translator Machine to Accept AFS Commands +

Controlling Optional Translator Features +

To configure an NFS/AFS translator machine +

To disable or enable Translator functionality, or set optional features +

Configuring NFS Client Machines + +

To configure an NFS client machine to access AFS +

Configuring User Accounts + +

To configure a user account for issuing AFS commands +

Authenticating on Unsupported NFS Client Machines + +

To authenticate using the knfs command +

To display tokens using the knfs command +

To discard tokens using the knfs command +

Appendix B. Using AFS Commands
+

AFS Command Syntax + +

Command Names +

Options +

Arguments +

Flags +

An Example Command +

Rules for Entering AFS Commands +

Rules for Using Abbreviations and Aliases +

Displaying Online Help for AFS Commands +

Appendix C. The afsmonitor Program Statistics
+

The Cache Manager Statistics + +

Performance Statistics Section (PerfStats_section) +

Server Up/Down Statistics Section (Server_UpDown_section) +

RPC Operation Measurements Section (RPCop_section) +

Authentication and Replicated File Access Section (Auth_Access_section) +

The File Server Statistics + +

Performance Statistics Section (PerfStats_section) +

RPC Operations Section (RPCop_section) +

Appendix D. AIX Audit Events
+

Introduction +

Audit-Specific Events +

Volume Server Events +

Backup Server Events +

Protection Server Events +

Authentication Events +

File Server and Cache Manager Interface Events +

BOS Server Events +

Volume Location Server Events +

Index
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd003.htm b/doc/html/AdminGuide/auagd003.htm new file mode 100644 index 0000000..55ff9bf --- /dev/null +++ b/doc/html/AdminGuide/auagd003.htm @@ -0,0 +1,37 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Figures

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd004.htm b/doc/html/AdminGuide/auagd004.htm new file mode 100644 index 0000000..13d87f0 --- /dev/null +++ b/doc/html/AdminGuide/auagd004.htm @@ -0,0 +1,32 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Tables

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd005.htm b/doc/html/AdminGuide/auagd005.htm new file mode 100644 index 0000000..2cdb097 --- /dev/null +++ b/doc/html/AdminGuide/auagd005.htm @@ -0,0 +1,145 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

About This Guide

This section describes the purpose, organization, and conventions of this +document. +

Audience and Purpose

This guide describes the concepts and procedures that an +AFS^{^(R)} system administrator needs to know. It assumes +familiarity with UNIX^{^(R)} administration, but no previous +knowledge of AFS. +

This document describes AFS commands in the context of specific +tasks. Thus, it does not describe all commands in detail. Refer +to the IBM AFS Administration Reference for detailed command +descriptions. +

Document Organization

This document groups AFS administrative tasks into the +following conceptual sections: +

Concepts and Configuration Issues +
Managing File Server Machines +
Managing Client Machines +
Managing Users and Groups +

The individual chapters in each section contain the following: +

A chapter overview +
A quick reference list of the tasks and commands described in the chapter +
An introduction to concepts that pertain to all of the tasks described in +the chapter +
A set of sections devoted to specific tasks. Each section begins +with a discussion of concepts specific to that task, followed by step-by-step +instructions for performing the task. The instructions are as specific +as has been judged practical. If two related procedures differ from one +another in important details, separate sets of instructions are usually +provided. +

How to Use This Document

When you need to perform a specific administrative task, +follow these steps: +

Determine if the task concerns file server machines, client machines, or +users and groups. Turn to the appropriate section in this document and +then to the appropriate chapter. +
Read or review the general introductory material at the beginning of the +chapter. +
Read or review the introductory material concerning the specific task you +wish to perform. +
Follow the step-by-step instructions for the task. +
If necessary, refer to the IBM AFS Administration Reference for +more detailed information about the commands. +

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. +

For additional information on AFS commands, including a description of +command string components, acceptable abbreviations and aliases, and how to +get online help for commands, see Appendix B, Using AFS Commands. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd006.htm b/doc/html/AdminGuide/auagd006.htm new file mode 100644 index 0000000..b1ea9bb --- /dev/null +++ b/doc/html/AdminGuide/auagd006.htm @@ -0,0 +1,780 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

An Overview of AFS Administration

This chapter provides a broad overview of the concepts and +organization of AFS. It is strongly recommended that anyone involved in +administering an AFS cell read this chapter before beginning to issue +commands. +

A Broad Overview of AFS

This section introduces most of the key terms and concepts +necessary for a basic understanding of AFS. For a more detailed +discussion, see More Detailed Discussions of Some Basic Concepts. +

AFS: A Distributed File System +

AFS is a distributed file system that enables users to share and +access all of the files stored in a network of computers as easily as they +access the files stored on their local machines. The file system is +called distributed for this exact reason: files can reside on many +different machines (be distributed across them), but are available to users on +every machine. +

Servers and Clients +

In fact, AFS stores files on a subset of the machines in a network, called +file server machines. File server machines provide file +storage and delivery service, along with other specialized services, to the +other subset of machines in the network, the client +machines. These machines are called clients because they make use +of the servers' services while doing their own work. In a standard +AFS configuration, clients provide computational power, access to the files in +AFS and other "general purpose" tools to the users seated at their +consoles. There are generally many more client workstations than file +server machines. +

AFS file server machines run a number of server processes, so +called because each provides a distinct specialized service: one handles +file requests, another tracks file location, a third manages security, and so +on. To avoid confusion, AFS documentation always refers to server +machines and server processes, not simply to +servers. For a more detailed description of the server +processes, see AFS Server Processes and the Cache Manager. +

Cells +

A cell is an administratively independent site running +AFS. As a cell's system administrator, you make many decisions +about configuring and maintaining your cell in the way that best serves its +users, without having to consult the administrators in other cells. For +example, you determine how many clients and servers to have, where to put +files, and how to allocate client machines to users. +

Transparent Access and the Uniform Namespace +

Although your AFS cell is administratively independent, you probably want +to organize the local collection of files (your filespace or +tree) so that users from other cells can also access the +information in it. AFS enables cells to combine their local filespaces +into a global filespace, and does so in such a way that file access +is transparent--users do not need to know anything about a +file's location in order to access it. All they need to know is +the pathname of the file, which looks the same in every cell. Thus +every user at every machine sees the collection of files in the same way, +meaning that AFS provides a uniform namespace to its users. +

Volumes +

AFS groups files into volumes, making it possible to distribute +files across many machines and yet maintain a uniform namespace. A +volume is a unit of disk space that functions like a container for a set of +related files, keeping them all together on one partition. Volumes can +vary in size, but are (by definition) smaller than a partition. +

Volumes are important to system administrators and users for several +reasons. Their small size makes them easy to move from one partition to +another, or even between machines. The system administrator can +maintain maximum efficiency by moving volumes to keep the load balanced +evenly. In addition, volumes correspond to directories in the +filespace--most cells store the contents of each user home directory in a +separate volume. Thus the complete contents of the directory move +together when the volume moves, making it easy for AFS to keep track of where +a file is at a certain time. Volume moves are recorded automatically, +so users do not have to keep track of file locations. +

Efficiency Boosters: Replication and Caching +

AFS incorporates special features on server machines and client machines +that help make it efficient and reliable. +

On server machines, AFS enables administrators to replicate +commonly-used volumes, such as those containing binaries for popular +programs. Replication means putting an identical read-only copy +(sometimes called a clone) of a volume on more than one file server +machine. The failure of one file server machine housing the volume does +not interrupt users' work, because the volume's contents are still +available from other machines. Replication also means that one machine +does not become overburdened with requests for files from a popular +volume. +

On client machines, AFS uses caching to improve +efficiency. When a user on a client workstation requests a file, the +Cache Manager on the client sends a request for the data to the +File Server process running on the proper file server machine. The user +does not need to know which machine this is; the Cache Manager determines +file location automatically. The Cache Manager receives the file from +the File Server process and puts it into the cache, an area of the +client machine's local disk or memory dedicated to temporary file +storage. Caching improves efficiency because the client does not need +to send a request across the network every time the user wants the same +file. Network traffic is minimized, and subsequent access to the file +is especially fast because the file is stored locally. AFS has a way of +ensuring that the cached file stays up-to-date, called a +callback. +

Security: Mutual Authentication and Access Control Lists +

Even in a cell where file sharing is especially frequent and widespread, it +is not desirable that every user have equal access to every file. One +way AFS provides adequate security is by requiring that servers and clients +prove their identities to one another before they exchange information. +This procedure, called mutual authentication, requires that both +server and client demonstrate knowledge of a "shared secret" (like a password) +known only to the two of them. Mutual authentication guarantees that +servers provide information only to authorized clients and that clients +receive information only from legitimate servers. +

Users themselves control another aspect of AFS security, by determining who +has access to the directories they own. For any directory a user owns, +he or she can build an access control list (ACL) that grants or +denies access to the contents of the directory. An access control list +pairs specific users with specific types of access privileges. There +are seven separate permissions and up to twenty different people or groups of +people can appear on an access control list. +

For a more detailed description of AFS's mutual authentication +procedure, see A More Detailed Look at Mutual Authentication. For further discussion of ACLs, see Managing Access Control Lists. +

More Detailed Discussions of Some Basic Concepts

The previous section offered a brief overview of the many +concepts that an AFS system administrator needs to understand. The +following sections examine some important concepts in more detail. +Although not all concepts are new to an experienced administrator, reading +this section helps ensure a common understanding of term and concepts. +

Networks

+ +

A network is a collection of interconnected computers able to +communicate with each other and transfer information back and forth. +

A networked computing environment contrasts with two types of computing +environments: mainframe and personal. + + +

A mainframe computing environment is the most +traditional. It uses a single powerful computer (the mainframe) to do +the majority of the work in the system, both file storage and +computation. It serves many users, who access their files and issue +commands to the mainframe via terminals, which generally have only +enough computing power to accept input from a keyboard and to display data on +the screen. + +
A personal computing environment is a single small computer +that serves one (or, at the most, a few) users. Like a mainframe +computer, the single computer stores all the files and performs all +computation. Like a terminal, the personal computer provides access to +the computer through a keyboard and screen. + +

A network can connect computers of any kind, but the typical network +running AFS connects high-function personal workstations. Each +workstation has some computing power and local disk space, usually more than a +personal computer or terminal, but less than a mainframe. For more +about the classes of machines used in an AFS environment, see Servers and Clients. +

Distributed File Systems

+ + +

A file system is a collection of files and the facilities +(programs and commands) that enable users to access the information in the +files. All computing environments have file systems. In a +mainframe environment, the file system consists of all the files on the +mainframe's storage disks, whereas in a personal computing environment it +consists of the files on the computer's local disk. +

Networked computing environments often use distributed file +systems like AFS. A distributed file system takes advantage of +the interconnected nature of the network by storing files on more than one +computer in the network and making them accessible to all of them. In +other words, the responsibility for file storage and delivery is "distributed" +among multiple machines instead of relying on only one. Despite the +distribution of responsibility, a distributed file system like AFS creates the +illusion that there is a single filespace. +

Servers and Clients

+ + + +

AFS uses a server/client model. In general, a server is a +machine, or a process running on a machine, that provides specialized services +to other machines. A client is a machine or process that +makes use of a server's specialized service during the course of its own +work, which is often of a more general nature than the server's. +The functional distinction between clients and server is not always strict, +however--a server can be considered the client of another server whose +service it is using. +

AFS divides the machines on a network into two basic classes, file +server machines and client machines, and assigns different +tasks and responsibilities to each. +

File Server Machines + + +

File server machines store the files in the distributed file +system, and a server process running on the file server machine +delivers and receives files. AFS file server machines run a number of +server processes. Each process has a special function, such +as maintaining databases important to AFS administration, managing security or +handling volumes. This modular design enables each server process to +specialize in one area, and thus perform more efficiently. For a +description of the function of each AFS server process, see AFS Server Processes and the Cache Manager. +

Not all AFS server machines must run all of the server processes. +Some processes run on only a few machines because the demand for their +services is low. Other processes run on only one machine in order to +act as a synchronization site. See The Four Roles for File Server Machines. +

Client Machines + +

The other class of machines are the client machines, which +generally work directly for users, providing computational power and other +general purpose tools. Clients also provide users with access to the +files stored on the file server machines. Clients do not run any +special processes per se, but do use a modified kernel that enables them to +communicate with the AFS server processes running on the file server machines +and to cache files. This collection of kernel modifications is referred +to as the Cache Manager; see The Cache Manager. There are usually many more client machines in a +cell than file server machines. +

Client and Server Configuration +

In the most typical AFS configuration, both file server machines and client +machines are high-function workstations with disk drives. While this +configuration is not required, it does have some advantages. + +

There are several advantages to using personal workstations as file server +machines. One is that it is easy to expand the network by adding +another file server machine. It is also easy to increase storage space +by adding disks to existing machines. Using workstations rather than +more powerful mainframes makes it more economical to use multiple file server +machines rather than one. Multiple file server machines provide an +increase in system availability and reliability if popular files are available +on more than one machine. +

The advantage of using workstations as clients is that caching +on the local disk speeds the delivery of files to application programs. +(For an explanation of caching, see Caching and Callbacks.) Diskless machines can access AFS if they are +running NFS^(R) and the NFS/AFS Translator, an optional component of the +AFS distribution. +

Cells

+ +

A cell is an independently administered site running AFS. +In terms of hardware, it consists of a collection of file server machines and +client machines defined as belonging to the cell; a machine can only +belong to one cell at a time. Users also belong to a cell in the sense +of having an account in it, but unlike machines can belong to (have an account +in) multiple cells. To say that a cell is administratively independent +means that its administrators determine many details of its configuration +without having to consult administrators in other cells or a central +authority. For example, a cell administrator determines how many +machines of different types to run, where to put files in the local tree, how +to associate volumes and directories, and how much space to allocate to each +user. +

The terms local cell and home cell are equivalent, +and refer to the cell in which a user has initially authenticated during a +session, by logging onto a machine that belongs to that cell. All other +cells are referred to as foreign from the user's +perspective. In other words, throughout a login session, a user is +accessing the filespace through a single Cache Manager--the one on the +machine to which he or she initially logged in--whose cell membership +defines the local cell. All other cells are considered foreign during +that login session, even if the user authenticates in additional cells or uses +the cd command to change directories into their file trees. + + + + +

It is possible to maintain more than one cell at a single geographical +location. For instance, separate departments on a university campus or +in a corporation can choose to administer their own cells. It is also +possible to have machines at geographically distant sites belong to the same +cell; only limits on the speed of network communication determine how +practical this is. +

Despite their independence, AFS cells generally agree to make their local +filespace visible to other AFS cells, so that users in different cells can +share files if they choose. If your cell is to participate in the +"global" AFS namespace, it must comply with a few basic conventions governing +how the local filespace is configured and how the addresses of certain file +server machines are advertised to the outside world. +

The Uniform Namespace and Transparent Access

+ + +

One of the features that makes AFS easy to use is that it provides +transparent access to the files in a cell's filespace. +Users do not have to know which file server machine stores a file in order to +access it; they simply provide the file's pathname, which AFS +automatically translates into a machine location. +

In addition to transparent access, AFS also creates a uniform +namespace--a file's pathname is identical regardless of which +client machine the user is working on. The cell's file tree looks +the same when viewed from any client because the cell's file server +machines store all the files centrally and present them in an identical manner +to all clients. +

To enable the transparent access and the uniform namespace features, the +system administrator must follow a few simple conventions in configuring +client machines and file trees. For details, see Making Other Cells Visible in Your Cell. +

Volumes

+ +

A volume is a conceptual container for a set of related files +that keeps them all together on one file server machine partition. +Volumes can vary in size, but are (by definition) smaller than a +partition. Volumes are the main administrative unit in AFS, and have +several characteristics that make administrative tasks easier and help improve +overall system performance. +

The relatively small size of volumes makes them easy to move from one +partition to another, or even between machines. +
You can maintain maximum system efficiency by moving volumes to keep the +load balanced evenly among the different machines. If a partition +becomes full, the small size of individual volumes makes it easy to find +enough room on other machines for them. + +
Each volume corresponds logically to a directory in the file tree and +keeps together, on a single partition, all the data that makes up the files in +the directory. By maintaining (for example) a separate volume for each +user's home directory, you keep all of the user's files together, +but separate from those of other users. This is an administrative +convenience that is impossible if the partition is the smallest unit of +storage. + +
+ +
+ +
The directory/volume correspondence also makes transparent file access +possible, because it simplifies the process of file location. All files +in a directory reside together in one volume and in order to find a file, a +file server process need only know the name of the file's parent +directory, information which is included in the file's pathname. +AFS knows how to translate the directory name into a volume name, and +automatically tracks every volume's location, even when a volume is moved +from machine to machine. For more about the directory/volume +correspondence, see Mount Points. +
Volumes increase file availability through replication and backup. + +
+ +
Replication (placing copies of a volume on more than one file server +machine) makes the contents more reliably available; for details, see Replication. Entire sets of volumes can be backed up to tape and +restored to the file system; see Configuring the AFS Backup System and Backing Up and Restoring AFS Data. In AFS, backup also refers to +recording the state of a volume at a certain time and then storing it (either +on tape or elsewhere in the file system) for recovery in the event files in it +are accidentally deleted or changed. See Creating Backup Volumes. +
Volumes are the unit of resource management. A space quota +associated with each volume sets a limit on the maximum volume size. +See Setting and Displaying Volume Quota and Current Size. + +

Mount Points

+ +

The previous section discussed how each volume corresponds logically to a +directory in the file system: the volume keeps together on one partition +all the data in the files residing in the directory. The directory that +corresponds to a volume is called its root directory, and the +mechanism that associates the directory and volume is called a mount +point. A mount point is similar to a symbolic link in the file +tree that specifies which volume contains the files kept in a +directory. A mount point is not an actual symbolic link; its +internal structure is different. +
Note: You must not create a symbolic link to a file whose name begins with the +number sign (#) or the percent sign (%), because the Cache Manager interprets +such a link as a mount point to a regular or read/write volume, +respectively. +
+

+ + + + +

The use of mount points means that many of the elements in an AFS file tree +that look and function just like standard UNIX file system directories are +actually mount points. In form, a mount point is a one-line file that +names the volume containing the data for files in the directory. When +the Cache Manager (see The Cache Manager) encounters a mount point--for example, in the course +of interpreting a pathname--it looks in the volume named in the mount +point. In the volume the Cache Manager finds an actual UNIX-style +directory element--the volume's root directory--that lists the +files contained in the directory/volume. The next element in the +pathname appears in that list. +

A volume is said to be mounted at the point in the file tree +where there is a mount point pointing to the volume. A volume's +contents are not visible or accessible unless it is mounted. +

Replication

+ + +

Replication refers to making a copy, or clone, of a +source read/write volume and then placing the copy on one or more additional +file server machines in a cell. One benefit of replicating a volume is +that it increases the availability of the contents. If one file server +machine housing the volume fails, users can still access the volume on a +different machine. No one machine need become overburdened with +requests for a popular file, either, because the file is available from +several machines. +

Replication is not necessarily appropriate for cells with limited disk +space, nor are all types of volumes equally suitable for replication +(replication is most appropriate for volumes that contain popular files that +do not change very often). For more details, see When to Replicate Volumes. +

Caching and Callbacks

+ +

Just as replication increases system availability, caching +increases the speed and efficiency of file access in AFS. Each AFS +client machine dedicates a portion of its local disk or memory to a +cache where it stores data temporarily. Whenever an +application program (such as a text editor) running on a client machine +requests data from an AFS file, the request passes through the Cache +Manager. The Cache Manager is a portion of the client machine's +kernel that translates file requests from local application programs into +cross-network requests to the File Server process running on the +file server machine storing the file. When the Cache Manager receives +the requested data from the File Server, it stores it in the cache and then +passes it on to the application program. +

Caching improves the speed of data delivery to application programs in the +following ways: +

When the application program repeatedly asks for data from the same file, +it is already on the local disk. The application does not have to wait +for the Cache Manager to request and receive the data from the File +Server. +
Caching data eliminates the need for repeated request and transfer of the +same data, so network traffic is reduced. Thus, initial requests and +other traffic can get through more quickly. + + +
+ +

+ +

+ + While caching provides many advantages, it also creates the problem of +maintaining consistency among the many cached copies of a file and the source +version of a file. This problem is solved using a mechanism referred to +as a callback. +

A callback is a promise by a File Server to a Cache Manager to inform the +latter when a change is made to any of the data delivered by the File +Server. Callbacks are used differently based on the type of file +delivered by the File Server: +

When a File Server delivers a writable copy of a file (from a read/write +volume) to the Cache Manager, the File Server sends along a callback with that +file. If the source version of the file is changed by another user, the +File Server breaks the callback associated with the cached version of that +file--indicating to the Cache Manager that it needs to update the cached +copy. +
When a File Server delivers a file from a read-only volume to the Cache +Manager, the File Server sends along a callback associated with the entire +volume (so it does not need to send any more callbacks when it delivers +additional files from the volume). Only a single callback is required +per accessed read-only volume because files in a read-only volume can change +only when a new version of the complete volume is released. All +callbacks associated with the old version of the volume are broken at release +time. +

The callback mechanism ensures that the Cache Manager always requests the +most up-to-date version of a file. However, it does not ensure that the +user necessarily notices the most current version as soon as the Cache Manager +has it. That depends on how often the application program requests +additional data from the File System or how often it checks with the Cache +Manager. +

AFS Server Processes and the Cache Manager

+ + +

As mentioned in Servers and Clients, AFS file server machines run a number of processes, each +with a specialized function. One of the main responsibilities of a +system administrator is to make sure that processes are running correctly as +much of the time as possible, using the administrative services that the +server processes provide. +

The following list briefly describes the function of each server process +and the Cache Manager; the following sections then discuss the important +features in more detail. +

The File Server, the most fundamental of the servers, delivers +data files from the file server machine to local workstations as requested, +and stores the files again when the user saves any changes to the +files. +

The Basic OverSeer Server (BOS Server) ensures that the other +server processes on its server machine are running correctly as much of the +time as possible, since a server is useful only if it is available. The +BOS Server relieves system administrators of much of the responsibility for +overseeing system operations. +

The Authentication Server helps ensure that communications on +the network are secure. It verifies user identities at login and +provides the facilities through which participants in transactions prove their +identities to one another (mutually authenticate). It maintains the +Authentication Database. +

The Protection Server helps users control who has access to +their files and directories. Users can grant access to several other +users at once by putting them all in a group entry in the Protection Database +maintained by the Protection Server. +

The Volume Server performs all types of volume +manipulation. It helps the administrator move volumes from one server +machine to another to balance the workload among the various machines. +

The Volume Location Server (VL Server) maintains the Volume +Location Database (VLDB), in which it records the location of volumes as they +move from file server machine to file server machine. This service is +the key to transparent file access for users. +

The Update Server distributes new versions of AFS server process +software and configuration information to all file server machines. It +is crucial to stable system performance that all server machines run the same +software. +

The Backup Server maintains the Backup Database, in which it +stores information related to the Backup System. It enables the +administrator to back up data from volumes to tape. The data can then +be restored from tape in the event that it is lost from the file +system. +

The Salvager is not a server in the sense that others +are. It runs only after the File Server or Volume Server fails; it +repairs any inconsistencies caused by the failure. The system +administrator can invoke it directly if necessary. +

The Network Time Protocol Daemon (NTPD) is not an AFS server +process per se, but plays a vital role nonetheless. It synchronizes the +internal clock on a file server machine with those on other machines. +Synchronized clocks are particularly important for correct functioning of the +AFS distributed database technology (known as Ubik); see Configuring the Cell for Proper Ubik Operation. The NTPD is controlled by the runntp +process. +

The Cache Manager is the one component in this list that resides +on AFS client rather than file server machines. It not a process per +se, but rather a part of the kernel on AFS client machines that communicates +with AFS server processes. Its main responsibilities are to retrieve +files for application programs running on the client and to maintain the files +in the cache. +

The File Server

+ +

The File Server is the most fundamental of the AFS server +processes and runs on each file server machine. It provides the same +services across the network that the UNIX file system provides on the local +disk: +

Delivering programs and data files to client workstations as requested and +storing them again when the client workstation finishes with them. +
Maintaining the hierarchical directory structure that users create to +organize their files. +
Handling requests for copying, moving, creating, and deleting files and +directories. +
Keeping track of status information about each file and directory +(including its size and latest modification time). +
Making sure that users are authorized to perform the actions they request +on particular files or directories. +
Creating symbolic and hard links between files. +
Granting advisory locks (corresponding to UNIX locks) on request. +

The Basic OverSeer Server

+ +

The Basic OverSeer Server (BOS Server) reduces the demands on +system administrators by constantly monitoring the processes running on its +file server machine. It can restart failed processes automatically and +provides a convenient interface for administrative tasks. +

The BOS Server runs on every file server machine. Its primary +function is to minimize system outages. It also +

Constantly monitors the other server processes (on the local machine) to +make sure they are running correctly. +
Automatically restarts failed processes, without contacting a human +operator. When restarting multiple server processes simultaneously, the +BOS server takes interdependencies into account and initiates restarts in the +correct order. + +
+ +
Accepts requests from the system administrator. Common reasons to +contact BOS are to verify the status of server processes on file server +machines, install and start new processes, stop processes either temporarily +or permanently, and restart dead processes manually. +
Helps system administrators to manage system configuration +information. The BOS server automates the process of adding and +changing server encryption keys, which are important in mutual +authentication. The BOS Server also provides a simple interface for +modifying two files that contain information about privileged users and +certain special file server machines. For more details about these +configuration files, see Common Configuration Files in the /usr/afs/etc Directory. +

The Authentication Server

+ +

The Authentication Server performs two main functions related to +network security: +

Verifying the identity of users as they log into the system by requiring +that they provide a password. The Authentication Server grants the user +a token as proof to AFS server processes that the user has +authenticated. For more on tokens, see Complex Mutual Authentication. +
Providing the means through which server and client processes prove their +identities to each other (mutually authenticate). This helps to create +a secure environment in which to send cross-network messages. +

In fulfilling these duties, the Authentication Server utilizes algorithms +and other procedures known as Kerberos (which is why many commands +used to contact the Authentication Server begin with the letter +k). This technology was originally developed by the +Massachusetts Institute of Technology's Project Athena. +

The Authentication Server also maintains the Authentication +Database, in which it stores user passwords converted into encryption +key form as well as the AFS server encryption key. To learn more about +the procedures AFS uses to verify user identity and during mutual +authentication, see A More Detailed Look at Mutual Authentication. + + + + +

The Protection Server

+ + + +

The Protection Server is the key to AFS's refinement of the +normal UNIX methods for protecting files and directories from unauthorized +use. The refinements include the following: +

Defining seven access permissions rather than the standard UNIX file +system's three. In conjunction with the UNIX mode bits associated +with each file and directory element, AFS associates an access control +list (ACL) with each directory. The ACL specifies which users +have which of the seven specific permissions for the directory and all the +files it contains. For a definition of AFS's seven access +permissions and how users can set them on access control lists, see Managing Access Control Lists. + +
Enabling users to grant permissions to numerous individual users--a +different combination to each individual if desired. UNIX protection +distinguishes only between three user or groups: the owner of the file, +members of a single specified group, and everyone who can access the local +file system. +
Enabling users to define their own groups of users, recorded in the +Protection Database maintained by the Protection Server. The +groups then appear on directories' access control lists as though they +were individuals, which enables the granting of permissions to many users +simultaneously. +
Enabling system administrators to create groups containing client machine +IP addresses to permit access when it originates from the specified client +machines. These types of groups are useful when it is necessary to +adhere to machine-based licensing restrictions. +

+ + +

The Protection Server's main duty is to help the File Server determine +if a user is authorized to access a file in the requested manner. The +Protection Server creates a list of all the groups to which the user +belongs. The File Server then compares this list to the ACL associated +with the file's parent directory. A user thus acquires access both +as an individual and as a member of any groups. +

The Protection Server also maps usernames (the name typed at the +login prompt) to AFS user ID numbers (AFS UIDs). +These UIDs are functionally equivalent to UNIX UIDs, but operate in the domain +of AFS rather than in the UNIX file system on a machine's local +disk. This conversion service is essential because the tokens that the +Authentication Server grants to authenticated users are stamped with usernames +(to comply with Kerberos standards). The AFS server processes identify +users by AFS UID, not by username. Before they can understand whom the +token represents, they need the Protection Server to translate the username +into an AFS UID. For further discussion of tokens, see A More Detailed Look at Mutual Authentication. +

The Volume Server

+ +

The Volume Server provides the interface through which you +create, delete, move, and replicate volumes, as well as prepare them for +archiving to tape or other media (backing up). Volumes explained the advantages gained by storing files in +volumes. Creating and deleting volumes are necessary when adding and +removing users from the system; volume moves are done for load +balancing; and replication enables volume placement on multiple file +server machines (for more on replication, see Replication). +

The Volume Location (VL) Server

+ + +

The VL Server maintains a complete list of volume locations in +the Volume Location Database (VLDB). When the Cache Manager +(see The Cache Manager) begins to fill a file request from an application program, +it first contacts the VL Server in order to learn which file server machine +currently houses the volume containing the file. The Cache Manager then +requests the file from the File Server process running on that file server +machine. +

The VLDB and VL Server make it possible for AFS to take advantage of the +increased system availability gained by using multiple file server machines, +because the Cache Manager knows where to find a particular file. +Indeed, in a certain sense the VL Server is the keystone of the entire file +system--when the information in the VLDB is inaccessible, the Cache +Manager cannot retrieve files, even if the File Server processes are working +properly. A list of the information stored in the VLDB about each +volume is provided in Volume Information in the VLDB. + +

The Update Server

+ +

The Update Server helps guarantee that all file server machines +are running the same version of a server process. System performance +can be inconsistent if some machines are running one version of the BOS Server +(for example) and other machines were running another version. +

To ensure that all machines run the same version of a process, install new +software on a single file server machine of each system type, called the +binary distribution machine for that type. The binary +distribution machine runs the server portion of the Update Server, +whereas all the other machines of that type run the client portion +of the Update Server. The client portions check frequently with the +server portion to see if they are running the right version of every +process; if not, the client portion retrieves the right version from the +binary distribution machine and installs it locally. The system +administrator does not need to remember to install new software individually +on all the file server machines: the Update Server does it +automatically. For more on binary distribution machines, see Binary Distribution Machines. + +

+ +

In cells that run the United States edition of AFS, the Update Server also +distributes configuration files that all file server machines need to store on +their local disks (for a description of the contents and purpose of these +files, see Common Configuration Files in the /usr/afs/etc Directory). As with server process software, the need for +consistent system performance demands that all the machines have the same +version of these files. With the United States edition, the system +administrator needs to make changes to these files on one machine only, the +cell's system control machine, which runs a server portion of +the Update Server. All other machines in the cell run a client portion +that accesses the correct versions of these configuration files from the +system control machine. Cells running the international edition of AFS +do not use a system control machine to distribute configuration files. +For more information, see The System Control Machine. +

The Backup Server

+ + +

The Backup Server maintains the information in the Backup +Database. The Backup Server and the Backup Database enable +administrators to back up data from AFS volumes to tape and restore it from +tape to the file system if necessary. The server and database together +are referred to as the Backup System. +

Administrators initially configure the Backup System by defining sets of +volumes to be dumped together and the schedule by which the sets are to be +dumped. They also install the system's tape drives and define the +drives' Tape Coordinators, which are the processes that +control the tape drives. +

Once the Backup System is configured, user and system data can be dumped +from volumes to tape. In the event that data is ever lost from the +system (for example, if a system or disk failure causes data to be lost), +administrators can restore the data from tape. If tapes are +periodically archived, or saved, data can also be restored to its state at a +specific time. Additionally, because Backup System data is difficult to +reproduce, the Backup Database itself can be backed up to tape and restored if +it ever becomes corrupted. For more information on configuring and +using the Backup System, see Configuring the AFS Backup System and Backing Up and Restoring AFS Data. +

The Salvager

+ +

The Salvager differs from other AFS Servers in that it runs only +at selected times. The BOS Server invokes the Salvager when the File +Server, Volume Server, or both fail. The Salvager attempts to repair +disk corruption that can result from a failure. +

As a system administrator, you can also invoke the Salvager as necessary, +even if the File Server or Volume Server has not failed. See Salvaging Volumes. +

The Network Time Protocol Daemon

+ +

The Network Time Protocol Daemon (NTPD) is not an AFS server +process per se, but plays an important role. It helps guarantee that +all of the file server machines agree on the time. The NTPD on one file +server machine acts as a synchronization site, generally learning the correct +time from a source outside the cell. The NTPDs on the other file server +machines refer to the synchronization site to set the internal clocks on their +machines. +

Keeping clocks synchronized is particularly important to the correct +operation of AFS's distributed database technology, which coordinates the +copies of the Authentication, Backup, Protection, and Volume Location +Databases; see Replicating the AFS Administrative Databases. Client machines also refer to these clocks for the +correct time; therefore, it is less confusing if all file server machines +have the same time. For more technical detail about the NTPD, see The runntp Process. +

The Cache Manager

+ +

As already mentioned in Caching and Callbacks, the Cache Manager is the one component in this +section that resides on client machines rather than on file server +machines. It is not technically a stand-alone process, but rather a set +of extensions or modifications in the client machine's kernel that enable +communication with the server processes running on server machines. Its +main duty is to translate file requests (made by application programs on +client machines) into remote procedure calls (RPCs) to the File Server. +(The Cache Manager first contacts the VL Server to find out which File Server +currently houses the volume that contains a requested file, as mentioned in The Volume Location (VL) Server). When the Cache Manager receives the requested file, +it caches it before passing data on to the application program. +

The Cache Manager also tracks the state of files in its cache compared to +the version at the File Server by storing the callbacks sent by the File +Server. When the File Server breaks a callback, indicating that a file +or volume changed, the Cache Manager requests a copy of the new version before +providing more data to application programs. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd007.htm b/doc/html/AdminGuide/auagd007.htm new file mode 100644 index 0000000..10b031e --- /dev/null +++ b/doc/html/AdminGuide/auagd007.htm @@ -0,0 +1,2375 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Issues in Cell Configuration and Administration

This chapter discusses many of the issues to consider when +configuring and administering a cell, and directs you to detailed related +information available elsewhere in this guide. It is assumed you are +already familiar with the material in An Overview of AFS Administration. +

It is best to read this chapter before installing your cell's first +file server machine or performing any other administrative task. + + + +

Differences between AFS and UNIX: A Summary

AFS behaves like a standard UNIX file system in most +respects, while also making file sharing easy within and between cells. +This section describes some differences between AFS and the UNIX file system, +referring you to more detailed information as appropriate. + +

Differences in File and Directory Protection

AFS augments the standard UNIX file protection mechanism in two +ways: it associates an access control list (ACL) +with each directory, and it enables users to define a large number of their +own groups, which can be placed on ACLs. +

AFS uses ACLs to protect files and directories, rather than relying +exclusively on the mode bits. This has several implications, which are +discussed further in the indicated sections: +

AFS ACLs use seven access permissions rather than the three UNIX mode +bits. See The AFS ACL Permissions. +
For directories, AFS ignores the UNIX mode bits. For files, AFS +uses only the first set of mode bits (the owner bits) , and their +meaning interacts with permissions on the directory's ACL. See How AFS Interprets the UNIX Mode Bits. +
A directory's ACL protects all of the files in a directory in the +same manner. To apply a more restrictive set of AFS permissions to +certain file, place it in directory with a different ACL. +
Moving a file to a different directory changes its protection. See Differences Between UFS and AFS Data Protection. +
An ACL can include about 20 entries granting different combinations of +permissions to different users or groups, rather than only the three UNIX +entities represented by the three sets of mode bits. See Differences Between UFS and AFS Data Protection. +
You can designate an AFS file as write-only as in the UNIX file system, by +setting only the w (write) mode bit. You cannot +designate an AFS directory as write-only, because AFS ignores the mode bits on +a directory. See How AFS Interprets the UNIX Mode Bits. +

AFS enables users to define the groups of other users. Placing these +groups on ACLs extends the same permissions to a number of exactly specified +users at the same time, which is much more convenient than placing the +individuals on the ACLs directly. See Administering the Protection Database. +

There are also system-defined groups, system:anyuser and +system:authuser, whose presence on an ACL extends access to a +wide range of users at once. See The System Groups and Using Groups on ACLs. + + +

Differences in Authentication

Just as the AFS filespace is distinct from each +machine's local file system, AFS authentication is separate from local +login. This has two practical implications, which are discussed further +in Using an AFS-modified login Utility. +

To access AFS files, users must both log into the local machine's +UNIX file system and authenticate with the AFS authentication service. +(Logging into the local UNIX file system is necessary because the AFS +filespace is accessed through the Cache Manager, which resides in the local +machine's kernel.) +
AFS provides a modified login utility for each system type that +accomplishes both local login and AFS authentication in one step, based on a +single password. If you choose not to use the AFS-modified login +utility, your users must login and authenticate in separate steps, as detailed +in the IBM AFS User Guide. +
Passwords are stored in two separate places: the Authentication +Database for AFS and each machine's local password file +(/etc/passwd or equivalent) for the UNIX file system. A +user's passwords in the two places can differ if desired, though the +resulting behavior depends on whether and how the cell is using an +AFS-modified login utility. +

Differences in the Semantics of Standard UNIX Commands

This section summarizes how AFS modifies the functionality of some UNIX +commands. +

The chmod command +

Only members of the system:administrators group can use +this command to turn on the setuid, setgid or sticky mode bits on AFS +files. For more information, see Determining if a Client Can Run Setuid Programs. + + +

The chown command +

Only members of the system:administrators group can issue +this command on AFS files. + + +

The chgrp command +

Only members of the system:administrators can issue this +command on AFS files and directories. + + +

The ftpd daemon +

The AFS-modified version of this daemon attempts to authenticate remote +issuers of the ftp command with the local AFS authentication +service. See Using UNIX Remote Services in the AFS Environment. + + +

The groups command +

If the user's AFS tokens are associated with a process authentication +group (PAG), the output of this command sometimes includes two large +numbers. To learn about PAGs, see Identifying AFS Tokens by PAG. + + +

The inetd daemon +

The AFS-modified version of this daemon authenticates remote issuers of +the AFS-modified rcp and rsh commands with the local AFS +authentication service. See Using UNIX Remote Services in the AFS Environment. +

The login utility +

AFS-modified login utilities both log the issuer into the local file +system and authenticate the user with the AFS authentication service. +See Using an AFS-modified login Utility. + + +

The ln command +

This command cannot create hard links between files in different AFS +directories. See Creating Hard Links. + + +

The rcp command +

The AFS-modified version of this command enables the issuer to access +files on the remote machine as an authenticated AFS user. See Using UNIX Remote Services in the AFS Environment. + + +

The rlogind daemon +

The AFS-modified version of this daemon authenticates remote issuers of +the rlogin command with the local AFS authentication +service. See Using UNIX Remote Services in the AFS Environment. +

The AFS distribution for some system types possibly does not include a +modified rlogind program. See the IBM AFS Release +Notes. + + +

The remsh or rsh command +

The AFS-modified version of this command enables the issuer to execute +commands on the remote machine as an authenticated AFS user. See Using UNIX Remote Services in the AFS Environment. +

+ + + + + + +

The AFS version of the fsck Command

Never run the standard UNIX fsck command on an AFS file +server machine. It does not understand how the File Server organizes +volume data on disk, and so moves all AFS data into the lost+found +directory on the partition. +

Instead, use the version of the fsck program that is included in +the AFS distribution. The IBM AFS Quick Beginnings explains +how to replace the vendor-supplied fsck program with the AFS +version as you install each server machine. +

The AFS version functions like the standard fsck program on data +stored on both UFS and AFS partitions. The appearance of a banner like +the following as the fsck program initializes confirms that you are +running the correct one: +

   --- AFS (R) version fsck---
+

where version is the AFS version. For correct results, it +must match the AFS version of the server binaries in use on the +machine. +

If you ever accidentally run the standard version of the program, contact +AFS Product Support immediately. It is sometimes possible to recover +volume data from the lost+found directory. + + +

Creating Hard Links

AFS does not allow hard links (created with the UNIX +ln command) between files that reside in different directories, +because in that case it is unclear which of the directory's ACLs to +associate with the link. +

AFS also does not allow hard links to directories, in order to keep the +file system organized as a tree. +

It is possible to create symbolic links (with the UNIX ln -s +command) between elements in two different AFS directories, or even between an +element in AFS and one in a machine's local UNIX file system. Do +not create a symbolic link to a file whose name begins with either a number +sign (#) or a percent sign (%), however. The +Cache Manager interprets such links as a mount point to a regular or +read/write volume, respectively. + + + +

AFS Implements Save on Close

When an application issues the UNIX close system +call on a file, the Cache Manager performs a synchronous write of the data to +the File Server that maintains the central copy of the file. It does +not return control to the application until the File Server has acknowledged +receipt of the data. For the fsync system call, control does +not return to the application until the File Server indicates that it has +written the data to non-volatile storage on the file server machine. +

When an application issues the UNIX write system call, the Cache +Manager writes modifications to the local AFS client cache only. If the +local machine crashes or an application program exits without issuing the +close system call, it is possible that the modifications are not +recorded in the central copy of the file maintained by the File Server. +The Cache Manager does sometimes write this type of modified data from the +cache to the File Server without receiving the close or +fsync system call, for example if it needs to free cache chunks for +new data. However, it is not generally possible to predict when the +Cache Manager transfers modified data to the File Server in this way. +

The implication is that if an application's Save option +invokes the write system call rather than close or +fsync, the changes are not necessarily stored permanently on the +File Server machine. Most application programs issue the +close system call for save operations, as well as when they finish +handling a file and when they exit. +

Setuid Programs

+ +

Set the UNIX setuid bit only for the local superuser root; +this does not present an automatic security risk: the local superuser +has no special privilege in AFS, but only in the local machine's UNIX +file system and kernel. +

Any file can be marked with the setuid bit, but only members of the +system:administrators group can issue the chown +system call or the /etc/chown command. +

The fs setcell command determines whether setuid programs that +originate in a foreign cell can run on a given client machine. See Determining if a Client Can Run Setuid Programs. + + + + +

Choosing a Cell Name

This section explains how to choose a cell name and explains +why choosing an appropriate cell name is important. +

Your cell name must distinguish your cell from all others in the AFS global +namespace. By conventions, the cell name is the second element in any +AFS pathname; therefore, a unique cell name guarantees that every AFS +pathname uniquely identifies a file, even if cells use the same directory +names at lower levels in their local AFS filespace. For example, both +the ABC Corporation cell and the State University cell can have a home +directory for the user pat, because the pathnames are +distinct: /afs/abc.com/usr/pat and +/afs/stateu.edu/usr/pat. +

By convention, cell names follow the ARPA Internet Domain System +conventions for site names. If you are already an Internet site, then +it is simplest to choose your Internet domain name as the cellname. +

If you are not an Internet site, it is best to choose a unique +Internet-style name, particularly if you plan to connect to the Internet in +the future. AFS Product Support is available for help in selecting an +appropriate name. There are a few constraints on AFS cell names: +

It can contain as many as 64 characters, but shorter names are better +because the cell name frequently is part of machine and file names. If +your cell name is long, you can reduce pathname length by creating a symbolic +link to the complete cell name, at the second level in your file tree. +See The Second (Cellname) Level. +
To guarantee it is suitable for different operating system types, the cell +name can contain only lowercase characters, numbers, underscores, dashes, and +periods. Do not include command shell metacharacters. +
It can include any number of fields, which are conventionally separated by +periods (see the examples below). +
It must end in a suffix that indicates the type of institution it is, or +the country in which it is situated. The following are some of the +standard suffixes: +
+
.com +
For businesses and other commercial organizations. Example: +abc.com for the ABC Corporation cell. +
.edu +
For educational institutions such as universities. Example: +stateu.edu for the State University cell. +
.gov +
For United States government institutions. +
.mil +
For United States military installations. +
+

Other suffixes are available if none of these are appropriate. + + +You can learn about suffixes by calling the Defense Data Network [Internet] +Network Information Center in the United States at (800) 235-3155. The +NIC can also provide you with the forms necessary for registering your cell +name as an Internet domain name. Registering your name prevents another +Internet site from adopting the name later. + + + + +

How to Set the Cell Name

The cell name is recorded in two files on the local disk of each file +server and client machine. Among other functions, these files define +the machine's cell membership and so affect how programs and processes +run on the machine; see Why Choosing the Appropriate Cell Name is Important. The procedure for setting the cell name is different +for the two types of machines. +

For file server machines, the two files that record the cell name are the +/usr/afs/etc/ThisCell and /usr/afs/etc/CellServDB +files. As described more explicitly in the IBM AFS Quick +Beginnings, you set the cell name in both by issuing the bos +setcellname command on the first file server machine you install in your +cell. It is not usually necessary to issue the command again. If +you run the United States edition of AFS and use the Update Server, it +distributes its copy of the ThisCell and CellServDB +files to additional server machines that you install. If you use the +international edition of AFS, the IBM AFS Quick Beginnings explains +how to copy the files manually. +

For client machines, the two files that record the cell name are the +/usr/vice/etc/ThisCell and /usr/vice/etc/CellServDB +files. You create these files on a per-client basis, either with a text +editor or by copying them onto the machine from a central source in +AFS. See Maintaining Knowledge of Database Server Machines for details. +

Change the cell name in these files only when you want to transfer the +machine to a different cell (it can only belong to one cell at a time). +If the machine is a file server, follow the complete set of instructions in +the IBM AFS Quick Beginnings for configuring a new cell. If +the machine is a client, all you need to do is change the files appropriately +and reboot the machine. The next section explains further the negative +consequences of changing the name of an existing cell. +

To set the default cell name used by most AFS commands without changing the +local /usr/vice/etc/ThisCell file, set the AFSCELL environment +variable in the command shell. It is worth setting this variable if you +need to complete significant administrative work in a foreign cell. +
Note: The fs checkservers and fs mkmount commands do not use +the AFSCELL variable. The fs checkservers command always +defaults to the cell named in the ThisCell file, unless the +-cell argument is used. The fs mkmount command +defaults to the cell in which the parent directory of the new mount point +resides. +
+ +

Why Choosing the Appropriate Cell Name is Important

Take care to select a cell name that is suitable for +long-term use. Changing a cell name later is complicated. An +appropriate cell name is important because it is the second element in the +pathname of all files in a cell's file tree. Because each cell +name is unique, its presence in an AFS pathname makes the pathname unique in +the AFS global namespace, even if multiple cells use similar filespace +organization at lower levels. For instance, it means that every cell +can have a home directory called /afs/cellname/usr/pat +without causing a conflict. The presence of the cell name in pathnames +also means that users in every cell use the same pathname to access a file, +whether the file resides in their local cell or in a foreign cell. +

Another reason to choose the correct cell name early in the process of +installing your cell is that the cell membership defined in each +machine's ThisCell file affects the performance of many +programs and processes running on the machine. For instance, AFS +commands (fs, kas, pts and vos +commands) by default execute in the cell of the machine on which they are +issued. The command interpreters check the ThisCell file on +the local disk and then contact the database server machines listed in the +CellServDB file for the indicated cell (the bos commands +work differently because the issuer always has to name of the machine on which +to run the command). +

The ThisCell file also determines the cell for which a user +receives an AFS token when he or she logs in to a machine. The cell +name also plays a role in security. As it converts a user password into +an encryption key for storage in the Authentication Database, the +Authentication Server combines the password with the cell name found in the +ThisCell file. AFS-modified login utilities use the same +algorithm to convert the user's password into an encryption key before +contacting the Authentication Server to obtain a token for the user. +(For a description of how AFS's security system uses encryption keys, see +A More Detailed Look at Mutual Authentication.) +

This method of converting passwords into encryption keys means that the +same password results in different keys in different cells. Even if a +user uses the same password in multiple cells, obtaining a user's token +from one cell does not enable unauthorized access to the user's account +in another cell. +

If you change the cell name, you must change the ThisCell and +CellServDB files on every server and client machine. Failure +to change them all can prevent login, because the encryption keys produced by +the login utility do not match the keys stored in the Authentication +Database. In addition, many commands from the AFS suites do not work as +expected. + + + +

Participating in the AFS Global Namespace

Participating in the AFS global namespace makes your +cell's local file tree visible to AFS users in foreign cells and makes +other cells' file trees visible to your local users. It makes file +sharing across cells just as easy as sharing within a cell. This +section outlines the procedures necessary for participating in the global +namespace. +

Participation in the global namespace is not mandatory. Some cells +use AFS primarily to facilitate file sharing within the cell, and are not +interested in providing their users with access to foreign cells. +
Making your file tree visible does not mean making it vulnerable. +You control how foreign users access your cell using the same protection +mechanisms that control local users' access. See Granting and Denying Foreign Users Access to Your Cell. +
The two aspects of participation are independent. A cell can make +its file tree visible without allowing its users to see foreign cells' +file trees, or can enable its users to see other file trees without +advertising its own. +
You make your cell visible to others by advertising your database server +machines. See Making Your Cell Visible to Others. +
You control access to foreign cells on a per-client machine basis. +In other words, it is possible to make a foreign cell accessible from one +client machine in your cell but not another. See Making Other Cells Visible in Your Cell. +

+ + + + + + +

What the Global Namespace Looks Like

The AFS global namespace appears the same to all AFS cells +that participate in it, because they all agree to follow a small set of +conventions in constructing pathnames. +

The first convention is that all AFS pathnames begin with the string +/afs to indicate that they belong to the AFS global +namespace. +

The second convention is that the cell name is the second element in an AFS +pathname; it indicates where the file resides (that is, the cell in which +a file server machine houses the file). As noted, the presence of a +cell name in pathnames makes the global namespace possible, because it +guarantees that all AFS pathnames are unique even if cells use the same +directory names at lower levels in their AFS filespace. +

What appears at the third and lower levels in an AFS pathname depends on +how a cell has chosen to arrange its filespace. There are some +suggested conventional directories at the third level; see The Third Level. + + + +

Making Your Cell Visible to Others

You make your cell visible to others by advertising your cell +name and database server machines. Just like client machines in the +local cell, the Cache Manager on machines in foreign cells use the information +to reach your cell's Volume Location (VL) Servers when they need volume +and file location information. Similarly, client-side authentication +programs running in foreign cells use the information to contact your +cell's authentication service. +

There are two places you can make this information available: +

In the global CellServDB file maintained by the AFS Product +Support group. This file lists the name and database server machines of +every cell that has agreed to make this information available to other +cells. +
To add or change your cell's listing in this file, have the official +support contact at your site call or write to AFS Product Support. +Changes to the file are frequent enough that AFS Product Support does not +announce each one. It is a good policy to check the file for changes on +a regular schedule. + + +
A file called CellServDB.local in the +/afs/cellname/service/etc directory of your +cell's filespace. List only your cell's database server +machines. +

Update the files whenever you change the identity of your cell's +database server machines. Also update the copies of the +CellServDB files on all of your server machines (in the +/usr/afs/etc directory) and client machines (in the +/usr/vice/etc directory). For instructions, see Maintaining the Server CellServDB File and Maintaining Knowledge of Database Server Machines. +

Once you have advertised your database server machines, it can be difficult +to make your cell invisible again. You can remove the +CellServDB.local file and ask AFS Product Support to remove +your entry from the global CellServDB file, but other cells +probably have an entry for your cell in their local CellServDB +files already. To make those entries invalid, you must change the names +or IP addresses of your database server machines. +

Your cell does not have to be invisible to be inaccessible, however. +To make your cell completely inaccessible to foreign users, remove the +system:anyuser group from all ACLs at the top three levels of +your filespace; see Granting and Denying Foreign Users Access to Your Cell. + + + + +

Making Other Cells Visible in Your Cell

To make a foreign cell's filespace visible on a client +machine in your cell, perform the following three steps: +

Mount the cell's root.cell volume at the second +level in your cell's filespace just below the /afs +directory. Use the fs mkmount command with the +-cell argument as instructed in To create a cellular mount point. +
Mount AFS at the /afs directory on the client machine. +The afsd program, which initializes the Cache Manager, performs the +mount automatically at the directory named in the first field of the local +/usr/vice/etc/cacheinfo file or by the command's +-mountdir argument. Mounting AFS at an alternate location +makes it impossible to reach the filespace of any cell that mounts its +root.afs and root.cell volumes at the +conventional locations. See Displaying and Setting the Cache Size and Location. +
Create an entry for the cell in the list of database server machines which +the Cache Manager maintains in kernel memory. +
The /usr/vice/etc/CellServDB file on every client machine's +local disk lists the database server machines for the local and foreign +cells. The afsd program reads the contents of the +CellServDB file into kernel memory as it initializes the Cache +Manager. You can also use the fs newcell command to add or +alter entries in kernel memory directly between reboots of the machine. +See Maintaining Knowledge of Database Server Machines. +

Note that making a foreign cell visible to client machines does not +guarantee that your users can access its filespace. The ACLs in the +foreign cell must also grant them the necessary permissions. + + +

Granting and Denying Foreign Users Access to Your Cell

Making your cell visible in the AFS global namespace does not +take away your control over the way in which users from foreign cells access +your file tree. +

By default, foreign users access your cell as the user +anonymous, which means they have only the permissions granted to +the system:anyuser group on each directory's ACL. +Normally these permissions are limited to the l (lookup) +and r (read) permissions. +

There are two ways to grant wider access to foreign users: +

Grant additional permissions to the system:anyuser group +on certain ACLs. Keep in mind, however, that all users can then access +that directory in the indicated way (not just specific foreign users you have +in mind). +
Create a local authentication account for specific foreign users, by +creating entries in the Protection and Authentication Databases and local +password file. It is not possible to place foreign usernames on ACLs, +nor to authenticate in a foreign cell without having an account in it. +

+ + + +

Configuring Your AFS Filespace

This section summarizes the issues to consider when +configuring your AFS filespace. For a discussion of creating volumes +that correspond most efficiently to the filespace's directory structure, +see Creating Volumes to Simplify Administration. +

Note for Windows users: Windows uses a backslash +( \ ) rather than a forward slash +( / ) to separate the elements in a +pathname. The hierarchical organization of the filespace is however the +same as on a UNIX machine. +

AFS pathnames must follow a few conventions so the AFS global namespace +looks the same from any AFS client machine. There are corresponding +conventions to follow in building your file tree, not just because pathnames +reflect the structure of a file tree, but also because the AFS Cache Manager +expects a certain configuration. + + +

The Top /afs Level

The first convention is that the top level in your file tree be called +the /afs directory. If you name it something else, then you +must use the -mountdir argument with the afsd program to +get Cache Managers to mount AFS properly. You cannot participate in the +AFS global namespace in that case. + + + +

The Second (Cellname) Level

The second convention is that just below the /afs +directory you place directories corresponding to each cell whose file tree is +visible and accessible from the local cell. Minimally, there must be a +directory for the local cell. Each such directory is a mount point to +the indicated cell's root.cell volume. For +example, in the ABC Corporation cell, /afs/abc.com is a +mount point for the cell's own root.cell volume and +stateu.edu is a mount point for the State University +cell's root.cell volume. The fs +lsmount command displays the mount points. +

   % fs lsmount /afs/abc.com 
+   '/afs/abc.com' is a mount point for volume '#root.cell'
+   % fs lsmount /afs/stateu.edu
+   '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
+

To reduce the amount of typing necessary in pathnames, you can create a +symbolic link with an abbreviated name to the mount point of each cell your +users frequently access (particularly the home cell). In the ABC +Corporation cell, for instance, /afs/abc is a symbolic link to the +/afs/abc.com mount point, as the fs lsmount +command reveals. +

   % fs lsmount /afs/abc
+   '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
+

+ + +

The Third Level

You can organize the third level of your cell's file +tree any way you wish. The following list describes directories that +appear at this level in the conventional configuration: +

common +

This directory contains programs and files needed by users working on +machines of all system types, such as text editors, online documentation +files, and so on. Its /etc subdirectory is a logical place +to keep the central update sources for files used on all of your cell's +client machines, such as the ThisCell and CellServDB +files. +

public +

A directory accessible to anyone who can access your filespace, because +its ACL grants the l (lookup) and r +(read) permissions to the system:anyuser +group. It is useful if you want to enable your users to make selected +information available to everyone, but do not want to grant foreign users +access to the contents of the usr directory which houses user home +directories ( and is also at this level). It is conventional to create +a subdirectory for each of your cell's users. +

service +

This directory contains files and subdirectories that help cells +coordinate resource sharing. For a list of the proposed standard files +and subdirectories to create, call or write to AFS Product Support. +

As an example, files that other cells expect to find in this +directory's etc subdirectory can include the following: +

CellServDB.export, a list of database server machines +for many cells +
CellServDB.local, a list of the cell's own database +server machines +
passwd, a copy of the local password file +(/etc/passwd or equivalent) kept on the local disk of the +cell's client machines +
group, a copy of the local groups file (/etc/group +or equivalent) kept on the local disk of the cell's client machines +

sys_type +

A separate directory for storing the server and client binaries for each +system type you use in the cell. Configuration is simplest if you use +the system type names assigned in the AFS distribution, particularly if you +wish to use the @sys variable in pathnames (see Using the @sys Variable in Pathnames). The IBM AFS Release Notes lists the +conventional name for each supported system type. +

Within each such directory, create directories named bin, +etc, usr, and so on, to store the programs normally kept +in the /bin, /etc and /usr directories on a +local disk. Then create symbolic links from the local directories on +client machines into AFS; see Configuring the Local Disk. Even if you do not choose to use symbolic links in +this way, it can be convenient to have central copies of system binaries in +AFS. If binaries are accidentally removed from a machine, you can +recopy them onto the local disk from AFS rather than having to recover them +from tape +

usr +

This directory contains home directories for your local users. As +discussed in the previous entry for the public directory, it is +often practical to protect this directory so that only locally authenticated +users can access it. This keeps the contents of your user's home +directories as secure as possible. +

If your cell is quite large, directory lookup can be slowed if you put all +home directories in a single usr directory. For suggestions +on distributing user home directories among multiple grouping directories, see +Grouping Home Directories. +

wsadmin +

This directory contains prototype, configuration and library files for use +with the package program. See Configuring Client Machines with the package Program. +

+ + + + +

Creating Volumes to Simplify Administration

This section discusses how to create volumes in ways that +make administering your system easier. +

At the top levels of your file tree (at least through the third level), +each directory generally corresponds to a separate volume. Some cells +also configure the subdirectories of some third level directories as separate +volumes. Common examples are the +/afs/cellname/common and +/afs/cellname/usr directories. +

You do not have to create a separate volume for every directory level in a +tree, but the advantage is that each volume tends to be smaller and easier to +move for load balancing. The overhead for a mount point is no greater +than for a standard directory, nor does the volume structure itself require +much disk space. Most cells find that below the fourth level in the +tree, using a separate volume for each directory is no longer +efficient. For instance, while each user's home directory (at the +fourth level in the tree) corresponds to a separate volume, all of the +subdirectories in the home directory normally reside in the same +volume. +

Keep in mind that only one volume can be mounted at a given directory +location in the tree. In contrast, a volume can be mounted at several +locations, though this is not recommended because it distorts the hierarchical +nature of the file tree, potentially causing confusion. + + + + + +

Assigning Volume Names

You can name your volumes anything you choose, subject to a few +restrictions: +

Read/write volume names can be up to 22 characters in length. The +maximum length for volume names is 31 characters, and there must be room to +add the .readonly extension on read-only volumes. +
Do not add the .readonly and .backup +extensions to volume names yourself, even if they are appropriate. The +Volume Server adds them automatically as it creates a read-only or backup +version of a volume. +
There must be volumes named root.afs and +root.cell, mounted respectively at the top (/afs) +level in the filespace and just below that level, at the cell's name (for +example, at /afs/abc.com in the ABC Corporation +cell). +
Deviating from these names only creates confusion and extra work. +Changing the name of the root.afs volume, for instance, +means that you must use the -rootvol argument to the +afsd program on every client machine, to name the alternate +volume. +
Similarly, changing the root.cell volume name prevents +users in foreign cells from accessing your filespace, if the mount point for +your cell in their filespace refers to the conventional +root.cell name. Of course, this is one way to make +your cell invisible to other cells. +

It is best to assign volume names that indicate the type of data they +contain, and to use similar names for volumes with similar contents. It +is also helpful if the volume name is similar to (or at least has elements in +common with) the name of the directory at which it is mounted. +Understanding the pattern then enables you accurately to guess what a volume +contains and where it is mounted. +

Many cells find that the most effective volume naming scheme puts a common +prefix on the names of all related volumes. Table 1 describes the recommended prefixing scheme. +
+

Table 1. Suggested volume prefixes
+ + + + + + + + +
Prefix + Contents + Example Name + Example Mount Point +
common. + popular programs and files + common.etc + /afs/cellname/common/etc +
src. + source code + src.afs + /afs/cellname/src/afs +
proj. + project data + proj.portafs + /afs/cellname/proj/portafs +
test. + testing or other temporary data + test.smith + /afs/cellname/usr/smith/test +
user. + user home directory data + user.terry + /afs/cellname/usr/terry +
sys_type. + programs compiled for an operating system type + rs_aix42.bin + /afs/cellname/rs_aix42/bin +
+

Prefix +	Contents +	Example Name +	Example Mount Point +
common. +	popular programs and files +	common.etc +	/afs/`cellname`/common/etc +
src. +	source code +	src.afs +	/afs/`cellname`/src/afs +
proj. +	project data +	proj.portafs +	/afs/`cellname`/proj/portafs +
test. +	testing or other temporary data +	test.smith +	/afs/`cellname`/usr/smith/test +
user. +	user home directory data +	user.terry +	/afs/`cellname`/usr/terry +
`sys_type`. +	programs compiled for an operating system type +	rs_aix42.bin +	/afs/`cellname`/rs_aix42/bin +

Table 2 is a more specific example for a cell's +rs_aix42 system volumes and directories: +
+

Table 2. Example volume-prefixing scheme
+ + + + + + + + + + + + + +
Example Name + Example Mount Point +
rs_aix42.bin + /afs/cellname/rs_aix42/bin/afs/cell/rs_aix42/bin +
rs_aix42.etc + /afs/cellname/rs_aix42/etc +
rs_aix42.usr + /afs/cellname/rs_aix42/usr +
rs_aix42.usr.afsws + /afs/cellname/rs_aix42/usr/afsws +
rs_aix42.usr.lib + /afs/cellname/rs_aix42/usr/lib +
rs_aix42.usr.bin + /afs/cellname/rs_aix42/usr/bin +
rs_aix42.usr.etc + /afs/cellname/rs_aix42/usr/etc +
rs_aix42.usr.inc + /afs/cellname/rs_aix42/usr/inc +
rs_aix42.usr.man + /afs/cellname/rs_aix42/usr/man +
rs_aix42.usr.sys + /afs/cellname/rs_aix42/usr/sys +
rs_aix42.usr.local + /afs/cellname/rs_aix42/usr/local +
+

Example Name +	Example Mount Point +
rs_aix42.bin +	/afs/`cellname`/rs_aix42/bin/afs/cell/rs_aix42/bin +
rs_aix42.etc +	/afs/`cellname`/rs_aix42/etc +
rs_aix42.usr +	/afs/`cellname`/rs_aix42/usr +
rs_aix42.usr.afsws +	/afs/`cellname`/rs_aix42/usr/afsws +
rs_aix42.usr.lib +	/afs/`cellname`/rs_aix42/usr/lib +
rs_aix42.usr.bin +	/afs/`cellname`/rs_aix42/usr/bin +
rs_aix42.usr.etc +	/afs/`cellname`/rs_aix42/usr/etc +
rs_aix42.usr.inc +	/afs/`cellname`/rs_aix42/usr/inc +
rs_aix42.usr.man +	/afs/`cellname`/rs_aix42/usr/man +
rs_aix42.usr.sys +	/afs/`cellname`/rs_aix42/usr/sys +
rs_aix42.usr.local +	/afs/`cellname`/rs_aix42/usr/local +

There are several advantages to this scheme: +

The volume name is similar to the mount point name in the +filespace. In all of the entries in Table 2, for example, the only difference between the +volume and mount point name is that the former uses periods as separators and +the latter uses slashes. Another advantage is that the volume name +indicates the contents, or at least suggests the directory on which to issue +the ls command to learn the contents. +
It makes it easy to manipulate groups of related volumes at one +time. In particular, the vos backupsys command's +-prefix argument enables you to create a backup version of every +volume whose name starts with the same string of characters. Making a +backup version of each volume is one of the first steps in backing up a volume +with the AFS Backup System, and doing it for many volumes with one command +saves you a good deal of typing. For instructions for creating backup +volumes, see Creating Backup Volumes, For information on the AFS Backup System, see Configuring the AFS Backup System and Backing Up and Restoring AFS Data. +
It makes it easy to group related volumes together on a partition. +Grouping related volumes together has several advantages of its own, discussed +in Grouping Related Volumes on a Partition. +

+ + +

Grouping Related Volumes on a Partition

If your cell is large enough to make it practical, consider +grouping related volumes together on a partition. In general, you need +at least three file server machines for volume grouping to be +effective. Grouping has several advantages, which are most obvious when +the file server machine becomes inaccessible: +

If you keep a hardcopy record of the volumes on a partition, you know +which volumes are unavailable. You can keep such a record without +grouping related volumes, but a list composed of unrelated volumes is much +harder to maintain. Note that the record must be on paper, because the +outage can prevent you from accessing an online copy or from issuing the +vos listvol command, which gives you the same information. +
The effect of an outage is more localized. For example, if all of +the binaries for a given system type are on one partition, then only users of +that system type are affected. If a partition houses binary volumes +from several system types, then an outage can affect more people, particularly +if the binaries that remain available are interdependent with those that are +not available. +

The advantages of grouping related volumes on a partition do not +necessarily extend to the grouping of all related volumes on one file server +machine. For instance, it is probably unwise in a cell with two file +server machines to put all system volumes on one machine and all user volumes +on the other. An outage of either machine probably affects +everyone. +

Admittedly, the need to move volumes for load balancing purposes can limit +the practicality of grouping related volumes. You need to weigh the +complementary advantages case by case. + + + + +

When to Replicate Volumes

As discussed in Replication, replication refers to making a copy, or +clone, of a read/write source volume and then placing the copy on one or more +additional file server machines. Replicating a volume can increase the +availability of the contents. If one file server machine housing the +volume becomes inaccessible, users can still access the copy of the volume +stored on a different machine. No one machine is likely to become +overburdened with requests for a popular file, either, because the file is +available from several machines. +

However, replication is not appropriate for all cells. If a cell +does not have much disk space, replication can be unduly expensive, because +each clone not on the same partition as the read/write source takes up as much +disk space as its source volume did at the time the clone was made. +Also, if you have only one file server machine, replication uses up disk space +without increasing availability. +

Replication is also not appropriate for volumes that change +frequently. You must issue the vos release command every +time you need to update a read-only volume to reflect changes in its +read/write source. +

For both of these reasons, replication is appropriate only for popular +volumes whose contents do not change very often, such as system binaries and +other volumes mounted at the upper levels of your filespace. User +volumes usually exist only in a read/write version since they change so +often. +

If you are replicating any volumes, you must replicate the +root.afs and root.cell volumes, preferably +at two or three sites each (even if your cell only has two or three file +server machines). The Cache Manager needs to pass through the +directories corresponding to the root.afs and +root.cell volumes as it interprets any pathname. The +unavailability of these volumes makes all other volumes unavailable too, even +if the file server machines storing the other volumes are still +functioning. +

Another reason to replicate the root.afs volume is that +it can lessen the load on the File Server machine. The Cache Manager +has a bias to access a read-only version of the root.afs +volume if it is replicate, which puts the Cache Manager onto the +read-only path through the AFS filespace. While on the +read-only path, the Cache Manager attempts to access a read-only copy of +replicated volumes. The File Server needs to track only one callback +per Cache Manager for all of the data in a read-only volume, rather than the +one callback per file it must track for read/write volumes. Fewer +callbacks translate into a smaller load on the File Server. +

If the root.afs volume is not replicated, the Cache +Manager follows a read/write path through the filespace, accessing the +read/write version of each volume. The File Server distributes and +tracks a separate callback for each file in a read/write volume, imposing a +greater load on it. +

For more on read/write and read-only paths, see The Rules of Mount Point Traversal. +

It also makes sense to replicate system binary volumes in many cases, as +well as the volume corresponding to the +/afs/cellname/usr directory and the volumes +corresponding to the /afs/cellname/common +directory and its subdirectories. +

It is a good idea to place a replica on the same partition as the +read/write source. In this case, the read-only volume is a clone (like +a backup volume): it is a copy of the source volume's vnode +index, rather than a full copy of the volume contents. Only if the +read/write volume moves to another partition or changes substantially does the +read-only volume consume significant disk space. Read-only volumes kept +on other partitions always consume the full amount of disk space that the +read/write source consumed when the read-only volume was created. +

The Default Quota and ACL on a New Volume

Every AFS volume has associated with it a quota that limits the amount +of disk space the volume is allowed to use. To set and change quota, +use the commands described in Setting and Displaying Volume Quota and Current Size. +

By default, every new volume is assigned a space quota of 5000 KB blocks +unless you include the -maxquota argument to the vos +create command. Also by default, the ACL on the root directory of +every new volume grants all permissions to the members of the +system:administrators group. To learn how to change +these values when creating an account with individual commands, see To create one user account with individual commands. When using uss commands to create +accounts, you can specify alternate ACL and quota values in the template +file's V instruction; see Creating a Volume with the V Instruction. + + + + + +

Configuring Server Machines

This section discusses some issues to consider when +configuring server machines, which store AFS data, transfer it to client +machines on request, and house the AFS administrative databases. To +learn about client machines, see Configuring Client Machines. +

If your cell has more than one AFS server machine, you can configure them +to perform specialized functions. A machine can assume one or more of +the roles described in the following list. For more details, see The Four Roles for File Server Machines. +

A simple file server machine runs only the processes that store +and deliver AFS files to client machines. You can run as many simple +file server machines as you need to satisfy your cell's performance and +disk space requirements. +
A database server machine runs the four database server +processes that maintain AFS's replicated administrative databases: +the Authentication, Backup, Protection, and Volume Location (VL) Server +processes. +
A binary distribution machine distributes the AFS server +binaries for its system type to all other server machines of that system +type. +
The single system control machine distributes common server +configuration files to all other server machines in the cell, in a cell that +runs the United States edition of AFS (cells that use the international +edition of AFS must not use the system control machine for this +purpose). The machine conventionally also serves as the time +synchronization source for the cell, adjusting its clock according to a time +source outside the cell. +

The IBM AFS Quick Beginnings explains how to configure your +cell's first file server machine to assume all four roles. The +IBM AFS Quick Beginnings chapter on installing additional server +machines also explains how to configure them to perform one or more +roles. + + + + +

Replicating the AFS Administrative Databases

The AFS administrative databases are housed on database +server machines and store information that is crucial for correct cell +functioning. Both server processes and Cache Managers access the +information frequently: +

Every time a Cache Manager fetches a file from a directory that it has not +previously accessed, it must look up the file's location in the Volume +Location Database (VLDB). +
Every time a user obtains an AFS token from the Authentication Server, the +server looks up the user's password in the Authentication +Database. +
The first time that a user accesses a volume housed on a specific file +server machine, the File Server contacts the Protection Server for a list of +the user's group memberships as recorded in the Protection +Database. +
Every time you back up a volume using the AFS Backup System, the Backup +Server creates records for it in the Backup Database. +

Maintaining your cell is simplest if the first machine has the lowest IP +address of any machine you plan to use as a database server machine. If +you later decide to use a machine with a lower IP address as a database server +machine, you must update the CellServDB file on all clients before +introducing the new machine. +

If your cell has more than one server machine, it is best to run more than +one as a database server machine (but more than three are rarely +necessary). Replicating the administrative databases in this way yields +the same benefits as replicating volumes: increased availability and +reliability. If one database server machine or process stops +functioning, the information in the database is still available from +others. The load of requests for database information is spread across +multiple machines, preventing any one from becoming overloaded. +

Unlike replicated volumes, however, replicated databases do change +frequently. Consistent system performance demands that all copies of +the database always be identical, so it is not acceptable to record changes in +only some of them. To synchronize the copies of a database, the +database server processes use AFS's distributed database technology, +Ubik. See Replicating the AFS Administrative Databases. +

If your cell has only one file server machine, it must also serve as a +database server machine. If you cell has two file server machines, it +is not always advantageous to run both as database server machines. If +a server, process, or network failure interrupts communications between the +database server processes on the two machines, it can become impossible to +update the information in the database because neither of them can alone elect +itself as the synchronization site. + + +

AFS Files on the Local Disk

It is generally simplest to store the binaries for all AFS +server processes in the /usr/afs/bin directory on every file server +machine, even if some processes do not actively run on the machine. +This makes it easier to reconfigure a machine to fill a new role. +

For security reasons, the /usr/afs directory on a file server +machine and all of its subdirectories and files must be owned by the local +superuser root and have only the first w +(write) mode bit turned on. Some files even have only the +first r (read) mode bit turned on (for example, the +/usr/afs/etc/KeyFile file, which lists the AFS server encryption +keys). Each time the BOS Server starts, it checks that the mode bits on +certain files and directories match the expected values. For a list, +see the IBM AFS Quick Beginnings section about protecting sensitive +AFS directories, or the discussion of the output from the bos +status command in To display the status of server processes and their BosConfig entries. +

For a description of the contents of all AFS directories on a file server +machine's local disk, see Administering Server Machines. +

Configuring Partitions to Store AFS Data

The partitions that house AFS volumes on a file server machine must be +mounted at directories named +

/vicepindex +

where index is one or two lowercase letters. By convention, +the first AFS partition created is mounted at the /vicepa +directory, the second at the /vicepb directory, and so on through +the /vicepz directory. The names then continue with +/vicepaa through /vicepaz, /vicepba through +/vicepbz, and so on, up to the maximum supported number of server +partitions, which is specified in the IBM AFS Release Notes. +

Each /vicepx directory must correspond to an entire +partition or logical volume, and must be a subdirectory of the root directory +( / ). It is not acceptable to configure part of (for example) the +/usr partition as an AFS server partition and mount it on a +directory called /usr/vicepa. +

Also, do not store non-AFS files on AFS server partitions. The File +Server and Volume Server expect to have available all of the space on the +partition. Sharing space also creates competition between AFS and the +local UNIX file system for access to the partition, particularly if the UNIX +files are frequently used. + + + + + +

Monitoring, Rebooting and Automatic Process Restarts

AFS provides several tools for monitoring the File Server, including +the scout and afsmonitor programs. You can +configure them to alert you when certain threshold values are exceeded, for +example when a server partition is more than 95% full. See Monitoring and Auditing AFS Performance. +

Rebooting a file server machine requires shutting down the AFS processes +and so inevitably causes a service outage. Reboot file server machines +as infrequently as possible. For instructions, see Rebooting a Server Machine. +

By default, the BOS Server on each file server machine stops and +immediately restarts all AFS server processes on the machine (including +itself) once a week, at 4:00 a.m. on Sunday. This +reduces the potential for the core leaks that can develop as any process runs +for an extended time. +

The BOS Server also checks each morning at 5:00 a.m. +for any newly installed binary files in the /usr/afs/bin +directory. It compares the timestamp on each binary file to the time at +which the corresponding process last restarted. If the timestamp on the +binary is later, the BOS Server restarts the corresponding process to start +using it. +

The default times are in the early morning hours when the outage that +results from restarting a process is likely to disturb the fewest number of +people. You can display the restart times for each machine with the +bos getrestart command, and set them with the bos +setrestart command. The latter command enables you to disable +automatic restarts entirely, by setting the time to never. +See Setting the BOS Server's Restart Times. + + +

Configuring Client Machines

This section summarizes issues to consider as you install and +configure client machines in your cell. + + + +

Configuring the Local Disk

You can often free up significant amounts of local disk space +on AFS client machines by storing standard UNIX files in AFS and creating +symbolic links to them from the local disk. The @sys +pathname variable can be useful in links to system-specific files; see Using the @sys Variable in Pathnames. +

There are two types of files that must actually reside on the local +disk: boot sequence files needed before the afsd program is +invoked, and files that can be helpful during file server machine +outages. +

During a reboot, AFS is inaccessible until the afsd program +executes and initializes the Cache Manager. (In the conventional +configuration, the AFS initialization file is included in the machine's +initialization sequence and invokes the afsd program.) Files +needed during reboot prior to that point must reside on the local disk. +They include the following, but this list is not necessarily +exhaustive. +

Standard UNIX utilities including the following or their +equivalents: +
- Machine initialization files (stored in the /etc or +/sbin directory on many system types) +
- The fstab file +
- The mount command binary +
- The umount command binary +
+
All subdirectories and files in the /usr/vice directory, +including the following: +
- The /usr/vice/cache directory +
- The /usr/vice/etc/afsd command binary +
- The /usr/vice/etc/cacheinfo file +
- The /usr/vice/etc/CellServDB file +
- The /usr/vice/etc/ThisCell file +
+
For more information on these files, see Configuration and Cache-Related Files on the Local Disk. +

The other type of files and programs to retain on the local disk are those +you need when diagnosing and fixing problems caused by a file server outage, +because the outage can make inaccessible the copies stored in AFS. +Examples include the binaries for a text editor (such as ed or +vi) and for the fs and bos commands. +Store copies of AFS command binaries in the /usr/vice/etc directory +as well as including them in the /usr/afsws directory, which is +normally a link into AFS. Then place the /usr/afsws +directory before the /usr/vice/etc directory in users' +PATH environment variable definition. When AFS is +functioning normally, users access the copy in the /usr/afsws +directory, which is more likely to be current than a local copy. +

You can automate the configuration of client machine local disks by using +the package program, which updates the contents of the local disk +to match a configuration file. See Configuring Client Machines with the package Program. + +

Enabling Access to Foreign Cells

As detailed in Making Other Cells Visible in Your Cell, you enable the Cache Manager to access a cell's +AFS filespace by storing a list of the cell's database server machines in +the local /usr/vice/etc/CellServDB file. The Cache Manager +reads the list into kernel memory at reboot for faster retrieval. You +can change the list in kernel memory between reboots by using the fs +newcell command. It is often practical to store a central version +of the CellServDB file in AFS and use the package +program periodically to update each client's version with the source +copy. See Maintaining Knowledge of Database Server Machines. +

Because each client machine maintains its own copy of the +CellServDB file, you can in theory enable access to different +foreign cells on different client machines. This is not usually +practical, however, especially if users do not always work on the same +machine. + + + +

Using the @sys Variable in Pathnames

When creating symbolic links into AFS on the local disk, it +is often practical to use the @sys variable in pathnames. The +Cache Manager automatically substitutes the local machine's AFS system +name (CPU/operating system type) for the @sys variable. This +means you can place the same links on machines of various system types and +still have each machine access the binaries for its system type. For +example, the Cache Manager on a machine running AIX 4.2 converts +/afs/abc.com/@sys to +/afs/abc.com/rs_aix42, whereas a machine running Solaris 7 +converts it to /afs/abc.com/sun4x_57. +

If you want to use the @sys variable, it is simplest to use the +conventional AFS system type names as specified in the IBM AFS Release +Notes. The Cache Manager records the local machine's system +type name in kernel memory during initialization. If you do not use the +conventional names, you must use the fs sysname command to change +the value in kernel memory from its default just after Cache Manager +initialization, on every client machine of the relevant system type. +The fs sysname command also displays the current value; see Displaying and Setting the System Type Name. +

In pathnames in the AFS filespace itself, use the @sys variable +carefully and sparingly, because it can lead to unexpected results. It +is generally best to restrict its use to only one level in the +filespace. The third level is a common choice, because that is where +many cells store the binaries for different machine types. +

Multiple instances of the @sys variable in a pathname are +especially dangerous to people who must explicitly change directories (with +the cd command, for example) into directories that store binaries +for system types other than the machine on which they are working, such as +administrators or developers who maintain those directories. After +changing directories, it is recommended that such people verify they are in +the desired directory. +

Setting Server Preferences

The Cache Manager stores a table of preferences for file server +machines in kernel memory. A preference rank pairs a file server +machine interface's IP address with an integer in the range from 1 to +65,534. When it needs to access a file, the Cache Manager compares the +ranks for the interfaces of all machines that house the file, and first +attempts to access the file via the interface with the best rank. As it +initializes, the Cache Manager sets default ranks that bias it to access files +via interfaces that are close to it in terms of network topology. You +can adjust the preference ranks to improve performance if you wish. +

The Cache Manager also uses similar preferences for Volume Location (VL) +Server machines. Use the fs getserverprefs command to +display preference ranks and the fs setserverprefs command to set +them. See Maintaining Server Preference Ranks. + +

Configuring AFS User Accounts

This section discusses some of the issues to consider when +configuring AFS user accounts. Because AFS is separate from the UNIX +file system, a user's AFS account is separate from her UNIX +account. +

The preferred method for creating a user account is with the uss +suite of commands. With a single command, you can create all the +components of one or many accounts, after you have prepared a template file +that guides the account creation. See Creating and Deleting User Accounts with the uss Command Suite. +

Alternatively, you can issue the individual commands that create each +component of an account. For instructions, along with instructions for +removing user accounts and changing user passwords, user volume quotas and +usernames, see Administering User Accounts. +

When users leave your system, it is often good policy to remove their +accounts. Instructions appear in Deleting Individual Accounts with the uss delete Command and Removing a User Account. +

An AFS user account consists of the following components, which are +described in greater detail in The Components of an AFS User Account. +

A Protection Database entry +
An Authentication Database entry +
A volume +
A home directory at which the volume is mounted +
Ownership of the home directory and full permissions on its ACL +
An entry in the local password file (/etc/passwd or equivalent) +of each machine the user needs to log into +
Optionally, standard files and subdirectories that make the account more +useful +

By creating some components but not others, you can create accounts at +different levels of functionality, using either uss commands as +described in Creating and Deleting User Accounts with the uss Command Suite or individual commands as described in Administering User Accounts. The levels of functionality include +the following +

An authentication-only account enables the user to obtain AFS +tokens and so to access protected AFS data and to issue privileged +commands. It consists only of entries in the Authentication and +Protection Database. This type of account is suitable for +administrative accounts and for users from foreign cells who need to access +protected data. Local users generally also need a volume and home +directory. +
A basic user account includes a volume for the user, in +addition to Authentication and Protection Database entries. The volume +is mounted in the AFS filespace as the user's home directory, and +provides a repository for the user's personal files. +
A full account adds configuration files for basic functions +such as logging in, printing, and mail delivery to a basic account, making it +more convenient and useful. For a discussion of some useful types of +configuration files, see Creating Standard Files in New AFS Accounts. +

If your users have UNIX user accounts that predate the introduction of AFS +in the cell, you possibly want to convert them into AFS accounts. There +are three main issues to consider: +

Making UNIX and AFS UIDs match +
Setting the password field in the local password file appropriately +
Moving files from the UNIX file system into AFS +

For further discussion, see Converting Existing UNIX Accounts with uss or Converting Existing UNIX Accounts. + + + + + +

Choosing Usernames and Naming Other Account Components

This section suggests schemes for choosing usernames, AFS +UIDs, user volume names and mount point names, and also outlines some +restrictions on your choices. +

Usernames +

AFS imposes very few restrictions on the form of usernames. It is +best to keep usernames short, both because many utilities and applications can +handle usernames of no more than eight characters and because by convention +many components of and AFS account incorporate the name. These include +the entries in the Protection and Authentication Databases, the volume, and +the mount point. Depending on your electronic mail delivery system, the +username can become part of the user's mailing address. The +username is also the string that the user types when logging in to a client +machine. +

Some common choices for usernames are last names, first names, initials, or +a combination, with numbers sometimes added. It is also best to avoid +using the following characters, many of which have special meanings to the +command shell. +

The comma ( , ) +
The colon ( : ), because AFS reserves it as a field +separator in protection group names; see The Two Types of User-Defined Groups +
The semicolon ( ; ) +
The "at-sign" ( @ ); this character is reserved for +Internet mailing addresses +
Spaces +
The newline character +
The period ( . ); it is conventional to use this +character only in the special username that an administrator adopts while +performing privileged tasks, such as pat.admin +

AFS UIDs and UNIX UIDs +

AFS associates a unique identification number, the AFS UID, with +every username, recording the mapping in the user's Protection Database +entry. The AFS UID functions within AFS much as the UNIX UID does in +the local file system: the AFS server processes and the Cache Manager +use it internally to identify a user, rather than the username. +

Every AFS user also must have a UNIX UID recorded in the local password +file (/etc/passwd or equivalent) of each client machine they log +onto. Both administration and a user's AFS access are simplest if +the AFS UID and UNIX UID match. One important consequence of matching +UIDs is that the owner reported by the ls -l command matches the +AFS username. +

It is usually best to allow the Protection Server to allocate the AFS UID +as it creates the Protection Database entry. However, both the pts +createuser command and the uss commands that create user +accounts enable you to assign AFS UIDs explicitly. This is appropriate +in two cases: +

You wish to group together the AFS UIDs of related users +
You are converting an existing UNIX account into an AFS account and want +to make the AFS UID match the existing UNIX UID +

After the Protection Server initializes for the first time on a cell's +first file server machine, it starts assigning AFS UIDs at a default +value. To change the default before creating any user accounts, or at +any time, use the pts setmax command to reset the max user +id counter. To display the counter, use the pts +listmax command. See Displaying and Setting the AFS UID and GID Counters. +

AFS reserves one AFS UID, 32766, for the user anonymous. +The AFS server processes assign this identity and AFS UID to any user who does +not possess a token for the local cell. Do not assign this AFS UID to +any other user or hardcode its current value into any programs or a +file's owner field, because it is subject to change in future +releases. + + +

User Volume Names +

Like any volume name, a user volume's base (read/write) name cannot +exceed 22 characters in length or include the .readonly or +.backup extension. See Creating Volumes to Simplify Administration. By convention, user volume names have the format +user.username. Using the +user. prefix not only makes it easy to identify the +volume's contents, but also to create a backup version of all user +volumes by issuing a single vos backupsys command. + + +

Mount Point Names +

By convention, the mount point for a user's volume is named after the +username. Many cells follow the convention of mounting user volumes in +the /afs/cellname/usr directory, as discussed +in The Third Level. Very large cells sometimes find that mounting all +user volumes in the same directory slows directory lookup, however; for +suggested alternatives, see the following section. + + +

Grouping Home Directories

Mounting user volumes in the +/afs/cellname/usr directory is an +AFS-appropriate variation on the standard UNIX practice of putting user home +directories under the /usr subdirectory. However, cells with +more than a few hundred users sometimes find that mounting all user volumes in +a single directory results in slow directory lookup. The solution is to +distribute user volume mount points into several directories; there are a +number of alternative methods to accomplish this. +

Distribute user home directories into multiple directories that reflect +organizational divisions, such as academic or corporate departments. +For example, a company can create group directories called +usr/marketing, usr/research, +usr/finance. A good feature of this scheme is that knowing a +user's department is enough to find the user's home +directory. Also, it makes it easy to set the ACL to limit access to +members of the department only. A potential drawback arises if +departments are of sufficiently unequal size that users in large departments +experience slower lookup than users in small departments. This scheme +is also not appropriate in cells where users frequently change between +divisions. +
Distribute home directories into alphabetic subdirectories of the +usr directory (the usr/a subdirectory, the +usr/b subdirectory, and so on), based on the first letter of the +username. If the cell is very large, create subdirectories under each +letter that correspond to the second letter in the user name. This +scheme has the same advantages and disadvantages of a department-based +scheme. Anyone who knows the user's username can find the +user's home directory, but users with names that begin with popular +letters sometimes experience slower lookup. +
Distribute home directories randomly but evenly into more than one +grouping directory. One cell that uses this scheme has over twenty such +directories called the usr1 directory, the usr2 +directory, and so on. This scheme is especially appropriate in cells +where the other two schemes do not seem feasible. It eliminates the +potential problem of differences in lookup speed, because all directories are +about the same size. Its disadvantage is that there is no way to guess +which directory a given user's volume is mounted in, but a solution is to +create a symbolic link in the regular usr directory that references +the actual mount point. For example, if user smith's +volume is mounted at the /afs/bigcell.com/usr17/smith +directory, then the /afs/bigcell.com/usr/smith directory is +a symbolic link to the ../usr17/smith +directory. This way, if someone does not know which directory the user +smith is in, he or she can access it through the link called +usr/smith; people who do know the appropriate directory save +lookup time by specifying it. +

For instructions on how to implement the various schemes when using the +uss program to create user accounts, see Evenly Distributing User Home Directories with the G Instruction and Creating a Volume with the V Instruction. +

Making a Backup Version of User Volumes Available

Mounting the backup version of a user's volume is a simple way to +enable users themselves to restore data they have accidentally removed or +deleted. It is conventional to mount the backup version at a +subdirectory of the user's home directory (called perhaps the +OldFiles subdirectory), but other schemes are possible. Once +per day you create a new backup version to capture the changes made that day, +overwriting the previous day's backup version with the new one. +Users can always retrieve the previous day's copy of a file without your +assistance, freeing you to deal with more pressing tasks. +

Users sometimes want to delete the mount point to their backup volume, +because they erroneously believe that the backup volume's contents count +against their quota. Remind them that the backup volume is separate, so +the only space it uses in the user volume is the amount needed for the mount +point. +

For further discussion of backup volumes, see Backing Up AFS Data and Creating Backup Volumes. + + + +

Creating Standard Files in New AFS Accounts

From your experience as a UNIX administrator, you are +probably familiar with the use of login and shell initialization files (such +as the .login and .cshrc files) to make an +account easier to use. +

It is often practical to add some AFS-specific directories to the +definition of the user's PATH environment variable, including +the following: +

The path to a bin subdirectory in the user's home +directory for binaries the user has created (that is, +/afs/cellname/usr/ +username/bin) +
The /usr/afsws/bin path, which conventionally includes programs +like fs, klog, kpasswd, pts, +tokens, and unlog +
The /usr/afsws/etc path, if the user is an administrator; +it usually houses the AFS command suites that require privilege (the +backup, butc, kas, uss, +vos commands), the package program, and others +

If you are not using an AFS-modified login utility, it can be helpful to +users to invoke the klog command in their .login +file so that they obtain AFS tokens as part of logging in. In the +following example command sequence, the first line echoes the string +klog to the standard output stream, so that the user understands +the purpose of the Password: prompt that appears when the +second line is executed. The -setpag flag associates the new +tokens with a process authentication group (PAG), which is discussed further +in Identifying AFS Tokens by PAG. +

   echo -n "klog "
+   klog -setpag
+

The following sequence of commands has a similar effect, except that the +pagsh command forks a new shell with which the PAG and tokens are +associated. +

   pagsh
+   echo -n "klog "
+   klog
+

If you use an AFS-modified login utility, this sequence is not necessary, +because such utilities both log a user in locally and obtain AFS +tokens. + + + + +

Using AFS Protection Groups

AFS enables users to define their own groups of +other users or machines. The groups are placed on ACLs to grant the +same permissions to many users without listing each user individually. +For group creation instructions, see Administering the Protection Database. +

Groups have AFS ID numbers, just as users do, but an AFS group ID (GID) is +a negative integer whereas a user's AFS UID is a positive integer. +By default, the Protection Server allocates a new group's AFS GID +automatically, but members of the system:administrators group +can assign a GID when issuing the pts creategroup command. +Before explicitly assigning a GID, it is best to verify that it is not already +in use. +

A group cannot belong to another group, but it can own another group or +even itself as long as it (the owning group) has at least one member. +The current owner of a group can transfer ownership of the group to another +user or group, even without the new owner's permission. At that +point the former owner loses administrative control over the group. +

By default, each user can create 20 groups. A system administrator +can increase or decrease this group creation quota with the pts +setfields command. +

Each Protection Database entry (group or user) is protected by a set of +five privacy flagswhich limit who can administer the entry and what +they can do. The default privacy flags are fairly restrictive, +especially for user entries. See Setting the Privacy Flags on Database Entries. + + + + +

The Three System Groups

As the Protection Server initializes for the first time on a +cell's first database server machine, it automatically creates three +group entries: the system:anyuser, +system:authuser, and system:administrators +groups. + +

The first two system groups are unlike any other groups in the Protection +Database in that they do not have a stable membership: +

The system:anyuser group includes everyone who can access +a cell's AFS filespace: users who have tokens for the local cell, +users who have logged in on a local AFS client machine but not obtained tokens +(such as the local superuser root), and users who have connected to +a local machine from outside the cell. Placing the +system:anyuser group on an ACL grants access to the widest +possible range of users. It is the only way to extend access to users +from foreign AFS cells that do not have local accounts. +
The system:authuser group includes everyone who has a +valid token obtained from the cell's AFS authentication service. +

Because the groups do not have a stable membership, the pts +membership command produces no output for them. Similarly, they +do not appear in the list of groups to which a user belongs. +

The system:administrators group does have a stable +membership, consisting of the cell's privileged administrators. +Members of this group can issue any pts command, and are the only +ones who can issue several other restricted commands (such as the +chown command on AFS files). By default, they also +implicitly have the a (administer) and l +(lookup) permissions on every ACL in the filespace. For +information about changing this default, see Administering the system:administrators Group. +

For a discussion of how to use system groups effectively on ACLs, see Using Groups on ACLs. +

The Two Types of User-Defined Groups

All users can create regular groups. A +regular group name has two fields separated by a colon, the first of which +must indicate the group's ownership. The Protection Server refuses +to create or change the name of a group if the result does not accurately +indicate the ownership. +

Members of the system:administrators group can create +prefix-less groups whose names do not have the first field that +indicates ownership. For suggestions on using the two types of groups +effectively, see Using Groups Effectively. + + +

Login and Authentication in AFS

As explained in Differences in Authentication, AFS authentication is separate from UNIX +authentication because the two file systems are separate. The +separation has two practical implications: +

To access AFS files, users must both log into the local file system and +authenticate with the AFS authentication service. (Logging into the +local file system is necessary because the only way to access the AFS +filespace is through a Cache Manager, which resides in the local +machine's kernel.) +
Passwords are stored in two separate places: in the Authentication +Database for AFS and in the each machine's local password file (the +/etc/passwd file or equivalent) for the local file system. +

When a user successfully authenticates, the AFS authentication service +passes a token to the user's Cache Manager. The token +is a small collection of data that certifies that the user has correctly +provided the password associated with a particular AFS identity. The +Cache Manager presents the token to AFS server processes along with service +requests, as proof that the user is genuine. To learn about the mutual +authentication procedure they use to establish identity, see A More Detailed Look at Mutual Authentication. +

The Cache Manager stores tokens in the user's credential structure in +kernel memory. To distinguish one user's credential structure from +another's, the Cache Manager identifies each one either by the +user's UNIX UID or by a process authentication group +(PAG), which is an identification number guaranteed to be unique in +the cell. For further discussion, see Identifying AFS Tokens by PAG. + +

A user can have only one token per cell in each separately identified +credential structure. To obtain a second token for the same cell, the +user must either log into a different machine or obtain another credential +structure with a different identifier than any existing credential structure, +which is most easily accomplished by issuing the pagsh command (see +Identifying AFS Tokens by PAG). In a single credential structure, a user can have +one token for each of many cells at the same time. As this implies, +authentication status on one machine or PAG is independent of authentication +status on another machine or PAG, which can be very useful to a user or system +administrator. +

The AFS distribution includes library files that enable each system +type's login utility to authenticate users with AFS and log them into the +local file system in one step. If you do not configure an AFS-modified +login utility on a client machine, its users must issue the klog +command to authenticate with AFS after logging in. +
Note: The AFS-modified libraries do not necessarily support all features available +in an operating system's proprietary login utility. In some cases, +it is not possible to support a utility at all. For more information +about the supported utilities in each AFS version, see the IBM AFS +Release Notes. +
+ + + + + + + +

Identifying AFS Tokens by PAG

As noted, the Cache Manager identifies user credential +structures either by UNIX UID or by PAG. Using a PAG is preferable +because it guaranteed to be unique: the Cache Manager allocates it based +on a counter that increments with each use. In contrast, multiple users +on a machine can share or assume the same UNIX UID, which creates potential +security problems. The following are two common such situations: +

The local superuser root can always assume any other +user's UNIX UID simply by issuing the su command, without +providing the user's password. If the credential structure is +associated with the user's UNIX UID, then assuming the UID means +inheriting the AFS tokens. +
Two users working on different NFS client machines can have the same UNIX +UID in their respective local file systems. If they both access the +same NFS/AFS Translator machine, and the Cache Manager there identifies them +by their UNIX UID, they become indistinguishable. To eliminate this +problem, the Cache Manager on a translator machine automatically generates a +PAG for each user and uses it, rather than the UNIX UID, to tell users +apart. +

Yet another advantage of PAGs over UIDs is that processes spawned by the +user inherit the PAG and so share the token; thus they gain access to AFS +as the authenticated user. In many environments, for example, printer +and other daemons run under identities (such as the local superuser +root) that the AFS server processes recognize only as the +anonymous user. Unless PAGs are used, such daemons cannot +access files for which the system:anyuser group does not have +the necessary ACL permissions. +

Once a user has a PAG, any new tokens the user obtains are associated with +the PAG. The PAG expires two hours after any associated tokens expire +or are discarded. If the user issues the klog command before +the PAG expires, the new token is associated with the existing PAG (the PAG is +said to be recycled in this case). +

AFS-modified login utilities automatically generate a PAG, as described in +the following section. If you use a standard login utility, your users +must issue the pagsh command before the klog command, or +include the latter command's -setpag flag. For +instructions, see Using Two-Step Login and Authentication. +

Users can also use either command at any time to create a new PAG. +The difference between the two commands is that the klog command +replaces the PAG associated with the current command shell and tokens. +The pagsh command initializes a new command shell before creating a +new PAG. If the user already had a PAG, any running processes or jobs +continue to use the tokens associated with the old PAG whereas any new jobs or +processes use the new PAG and its associated tokens. When you exit the +new shell (by pressing <Ctrl-d>, for example), you return to the +original PAG and shell. By default, the pagsh command +initializes a Bourne shell, but you can include the -c argument to +initialize a C shell (the /bin/csh program on many system types) or +Korn shell (the /bin/ksh program) instead. + +

Using an AFS-modified login Utility

As previously mentioned, an AFS-modified login utility +simultaneously obtains an AFS token and logs the user into the local file +system. This section outlines the login and authentication process and +its interaction with the value in the password field of the local password +file. +

An AFS-modified login utility performs a sequence of steps similar to the +following; details can vary for different operating systems: +

It checks the user's entry in the local password file (the +/etc/passwd file or equivalent). +
If no entry exists, or if an asterisk ( * ) appears in the +entry's password field, the login attempt fails. If the entry +exists, the attempt proceeds to the next step. +
The utility obtains a PAG. +
The utility converts the password provided by the user into an +encryption key and encrypts a packet of data with the key. It sends the +packet to the AFS authentication service (the AFS Authentication Server in the +conventional configuration). +
The authentication service decrypts the packet and, depending on the +success of the decryption, judges the password to be correct or +incorrect. (For more details, see A More Detailed Look at Mutual Authentication.) +
- If the authentication service judges the password incorrect, the user does +not receive an AFS token. The PAG is retained, ready to be associated +with any tokens obtained later. The attempt proceeds to Step 6. +
- If the authentication service judges the password correct, it issues a +token to the user as proof of AFS authentication. The login utility +logs the user into the local UNIX file system. Some login utilities +echo the following banner to the screen to alert the user to authentication +with AFS. Step 6 is skipped. +
```
   AFS(R) version Login 
+
```
  +
+
If no AFS token was granted in Step 4, the login utility attempts to log the user into the local +file system, by comparing the password provided to the local password +file. +
- If the password is incorrect or any value other than an encrypted +13-character string appears in the password field, the login attempt +fails. +
- If the password is correct, the user is logged into the local file system +only. +
+

+ + + +

As indicated, when you use an AFS-modified login utility, the password +field in the local password file is no longer the primary gate for access to +your system. If the user provides the correct AFS password, then the +program never consults the local password file. However, you can still +use the password field to control access, in the following way: +

To prevent both local login and AFS authentication, place an asterisk ( +* ) in the field. This is useful mainly in emergencies, when +you want to prevent a certain user from logging into the machine. +
To prevent login to the local file system if the user does not provide the +correct AFS password, place a character string of any length other than the +standard thirteen characters in the field. This is appropriate if you +want to permit only people with local AFS accounts to login on your +machines. A single X or other character is the most easily +recognizable way to do this. +
To enable a user to log into the local file system even after providing an +incorrect AFS password, record a standard UNIX encrypted password in the field +by issuing the standard UNIX password-setting command (passwd or +equivalent). +

Systems that use a Pluggable Authentication Module (PAM) for login and AFS +authentication do not necessarily consult the local password file at all, in +which case they do not use the password field to control authentication and +login attempts. Instead, instructions in the PAM configuration file (on +many system types, /etc/pam.conf) fill the same +function. See the instructions in the IBM AFS Quick +Beginnings for installing AFS-modified login utilities. + +

Using Two-Step Login and Authentication

In cells that do not use an AFS-modified login utility, users +must issue separate commands to login and authenticate, as detailed in the +IBM AFS User Guide: +

They use the standard login program to login to the local file +system, providing the password listed in the local password file (the +/etc/passwd file or equivalent). +
They must issue the klog command to authenticate with the AFS +authentication service, including its -setpag flag to associate the +new tokens with a process authentication group (PAG). +

As mentioned in Creating Standard Files in New AFS Accounts, you can invoke the klog -setpag command in a +user's .login file (or equivalent) so that the user +does not have to remember to issue the command after logging in. The +user still must type a password twice, once at the prompt generated by the +login utility and once at the klog command's prompt. +This implies that the two passwords can differ, but it is less confusing if +they do not. +

Another effect of not using an AFS-modified login utility is that the AFS +servers recognize the standard login program as the +anonymous user. If the login program needs to +access any AFS files (such as the .login file in a +user's home directory), then the ACL that protects the file must include +an entry granting the l (lookup) and r +(read) permissions to the system:anyuser +group. +

When you do not use an AFS-modified login utility, an actual (scrambled) +password must appear in the local password file for each user. Use the +/bin/passwd file to insert or change these passwords. It is +simpler if the password in the local password file matches the AFS password, +but it is not required. + + + + + + + + + + + + + + +

Obtaining, Displaying, and Discarding Tokens

Once logged in, a user can obtain a token at any time with the +klog command. If a valid token already exists, the new one +overwrites it. If a PAG already exists, the new token is associated +with it. +

By default, the klog command authenticates the issuer using the +identity currently logged in to the local file system. To authenticate +as a different identity, use the -principal argument. To +obtain a token for a foreign cell, use the -cell argument (it can +be combined with the -principal argument). See the IBM +AFS User Guide and the entry for the klog command in the +IBM AFS Administration Reference. +

To discard either all tokens or the token for a particular cell, issue the +unlog command. The command affects only the tokens +associated with the current command shell. See the IBM AFS User +Guideand the entry for the unlog command in the IBM AFS +Administration Reference. +

To display the tokens associated with the current command shell, issue the +tokens command. The following examples illustrate its output +in various situations. +

If the issuer is not authenticated in any cell: +

   % tokens
+   Tokens held by the Cache Manager:
+          --End of list--
+

The following shows the output for a user with AFS UID 1000 in the ABC +Corporation cell: +

   % tokens
+   Tokens held by the Cache Manager: 
+   
+   User's (AFS ID 1000) tokens for afs@abc.com  [Expires Jun  2 10:00]
+       --End of list--
+

The following shows the output for a user who is authenticated in ABC +Corporation cell, the State University cell and the DEF Company cell. +The user has different AFS UIDs in the three cells. Tokens for the last +cell are expired: +

   % tokens
+   Tokens held by the Cache Manager:
+    
+   User's (AFS ID 1000) tokens for afs@abc.com  [Expires Jun  2 10:00]
+   User's (AFS ID 4286) tokens for afs@stateu.edu  [Expires Jun  3 1:34]
+   User's (AFS ID 22) tokens for afs@def.com  [>>Expired<<]
+       --End of list--
+

The Kerberos version of the tokens command (the +tokens.krb command), also reports information on the +ticket-granting ticket, including the ticket's owner, the ticket-granting +service, and the expiration date, as in the following example. Also see +Support for Kerberos Authentication. +

   % tokens.krb
+   Tokens held by the Cache Manager:
+   User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun  2 10:00]
+   User smith's tokens for krbtgt.ABC.COM@abc.com [Expires Jun  2 10:00]
+     --End of list--
+

Setting Default Token Lifetimes for Users

+ +

The maximum lifetime of a user token is the smallest of the ticket +lifetimes recorded in the following three Authentication Database +entries. The kas examine command reports the lifetime as +Max ticket lifetime. Administrators who have the +ADMIN flag on their Authentication Database entry can use the +-lifetime argument to the kas setfields command to set +an entry's ticket lifetime. +

The afs entry, which corresponds to the AFS server +processes. The default is 100 hours. +
The krbtgt.cellname entry, which corresponds to +the ticket-granting ticket used internally in generating the token. The +default is 720 hours (30 days). +
The entry for the user of the AFS-modified login utility or issuer of the +klog command. The default is 25 hours for user entries +created using the AFS 3.1 or later version of the Authentication +Server, and 100 hours for user entries created using the AFS 3.0 +version of the Authentication Server. A user can use the kas +examine command to display his or her own Authentication Database +entry. +

Note:

An AFS-modified login utility always grants a token with a lifetime +calculated from the previously described three values. When issuing the +klog command, a user can request a lifetime shorter than the +default by using the -lifetime argument. For further +information, see the IBM AFS User Guide and the klog +reference page in the IBM AFS Administration Reference. +

Changing Passwords

+ + + + + +

Regular AFS users can change their own passwords by using either the +kpasswd or kas setpassword command. The commands +prompt for the current password and then twice for the new password, to screen +out typing errors. +

Administrators who have the ADMIN flag on their Authentication +Database entries can change any user's password, either by using the +kpasswd command (which requires knowing the current password) or +the kas setpassword command. +

If your cell does not use an AFS-modified login utility, remember also to +change the local password, using the operating system's password-changing +command. For more instructions on changing passwords, see Changing AFS Passwords. +

Imposing Restrictions on Passwords and Authentication Attempts

You can help to make your cell more secure by imposing restrictions on +user passwords and authentication attempts. To impose the restrictions +as you create an account, use the A instruction in the +uss template file as described in Increasing Account Security with the A Instruction. To set or change the values on an existing +account, use the kas setfields command as described in Improving Password and Authentication Security. + + + + + + +

By default, AFS passwords never expire. Limiting password lifetime +can help improve security by decreasing the time the password is subject to +cracking attempts. You can choose an lifetime from 1 to 254 days after +the password was last changed. It automatically applies to each new +password as it is set. When the user changes passwords, you can also +insist that the new password is not similar to any of the 20 passwords +previously used. + + + + +

Unscrupulous users can try to gain access to your AFS cell by guessing an +authorized user's password. To protect against this type of +attack, you can limit the number of times that a user can consecutively fail +to provide the correct password. When the limit is exceeded, the +authentication service refuses further authentication attempts for a specified +period of time (the lockout time). To reenable +authentication attempts before the lockout time expires, an administrator must +issue the kas unlock command. + + + + + + +

In addition to settings on user's authentication accounts, you can +improve security by automatically checking the quality of new user +passwords. The kpasswd and kas setpassword +commands pass the proposed password to a program or script called +kpwvalid, if it exists. The kpwvalid performs +quality checks and returns a code to indicate whether the password is +acceptable. You can create your own program or modified the sample +program included in the AFS distribution. See the kpwvalid +reference page in the IBM AFS Administration Reference. +

There are several types of quality checks that can improve password +quality. +

The password is a minimum length +
The password is not a word +
The password contains both numbers and letters +

Support for Kerberos Authentication

+ + + + + + + +

If your site is using standard Kerberos authentication rather than the AFS +Authentication Server, use the modified versions of the klog, +pagsh, and tokens commands that support Kerberos +authentication. The binaries for the modified version of these commands +have the same name as the standard binaries with the addition of a +.krb extension. +

Use either the Kerberos version or the standard command throughout the +cell; do not mix the two versions. AFS Product Support can provide +instructions on installing the Kerberos version of these four commands. +For information on the differences between the two versions of these commands, +see the IBM AFS Administration Reference. +

Security and Authorization in AFS

AFS incorporates several features to ensure that only +authorized users gain access to data. This section summarizes the most +important of them and suggests methods for improving security in your +cell. +

Some Important Security Features

+ + +

ACLs on Directories +

Files in AFS are protected by the access control list (ACL) associated with +their parent directory. The ACL defines which users or groups can +access the data in the directory, and in what way. See Managing Access Control Lists. +

Mutual Authentication Between Client and Server +

When an AFS client and server process communicate, each requires the other +to prove its identity during mutual authentication, which involves the +exchange of encrypted information that only valid parties can decrypt and +respond to. For a detailed description of the mutual authentication +process, see A More Detailed Look at Mutual Authentication. +

AFS server processes mutually authenticate both with one another and with +processes that represent human users. After mutual authentication is +complete, the server and client have established an authenticated connection, +across which they can communicate repeatedly without having to authenticate +again until the connection expires or one of the parties closes it. +Authenticated connections have varying lifetimes. +

Tokens +

In order to access AFS files, users must prove their identities to the AFS +authentication service by providing the correct AFS password. If the +password is correct, the authentication service sends the user a +token as evidence of authenticated status. See Login and Authentication in AFS. +

Servers assign the user identity anonymous to users and +processes that do not have a valid token. The anonymous +identity has only the access granted to the system:anyuser +group on ACLs. +

Authorization Checking +

Mutual authentication establishes that two parties communicating with one +another are actually who they claim to be. For many functions, AFS +server processes also check that the client whose identity they have verified +is also authorized to make the request. Different requests require +different kinds of privilege. See Three Types of Privilege. +

Encrypted Network Communications + + + +

The AFS server processes encrypt particularly sensitive information before +sending it back to clients. Even if an unauthorized party is able to +eavesdrop on an authenticated connection, they cannot decipher encrypted data +without the proper key. +

The following AFS commands encrypt data because they involve server +encryption keys and passwords: +

The bos addkey command, which adds a server encryption key to +the /usr/afs/etc/KeyFile file +
The bos listkeys command, which lists the server encryption +keys from the /usr/afs/etc/KeyFile file +
The kpasswd command, which changes a password in the +Authentication Database +
Most commands in the kas command suite +

In addition, the United States edition of the Update Server encrypts +sensitive information (such as the contents of KeyFile) when +distributing it. Other commands in the bos suite and the +commands in the fs, pts and vos suites do not +encrypt data before transmitting it. +

Three Types of Privilege

AFS uses three separate types of privilege for the reasons +discussed in The Reason for Separate Privileges. +

Membership in the system:administrators group. +Members are entitled to issue any pts command and those +fs commands that set volume quota. By default, they also +implicitly have the a (administer) and l +(lookup) permissions on every ACL in the file tree even if the ACL +does not include an entry for them. +
The ADMIN flag on the Authentication Database entry. An +administrator with this flag can issue any kas command. +
Inclusion in the /usr/afs/etc/UserList file. An +administrator whose username appears in this file can issue any +bos, vos, or backup command (although some +backup commands require additional privilege as described in Granting Administrative Privilege to Backup Operators). +

Authorization Checking versus Authentication

AFS distinguishes between authentication and authorization +checking. Authentication refers to the process of proving +identity. Authorization checking refers to the process of +verifying that an authenticated identity is allowed to perform a certain +action. +

AFS implements authentication at the level of connections. Each time +two parties establish a new connection, they mutually authenticate. In +general, each issue of an AFS command establishes a new connection between AFS +server process and client. +

AFS implements authorization checking at the level of server +machines. If authorization checking is enabled on a server machine, +then all of the server processes running on it provide services only to +authorized users. If authorization checking is disabled on a server +machine, then all of the server processes perform any action for +anyone. Obviously, disabling authorization checking is an extreme +security exposure. For more information, see Managing Authentication and Authorization Requirements. +

Improving Security in Your Cell

+ +

You can improve the level of security in your cell by configuring user +accounts, server machines, and system administrator accounts in the indicated +way. +

User Accounts +

Use an AFS-modified login utility, or include the -setpag flag +to the klog command, to associate the credential structure that +houses tokens with a PAG rather than a UNIX UID. This prevents users +from inheriting someone else's tokens by assuming their UNIX +identity. For further discussion, see Identifying AFS Tokens by PAG. +
Encourage users to issue the unlog command to destroy their +tokens before logging out. This forestalls attempts to access tokens +left behind kernel memory. Consider including the unlog +command in every user's .logout file or +equivalent. +

Server Machines +

Disable authorization checking only in emergencies or for very brief +periods of time. It is best to work at the console of the affected +machine during this time, to prevent anyone else from accessing the machine +through the keyboard. +
Change the AFS server encryption key on a frequent and regular +schedule. Make it difficult to guess (a long string including +nonalphabetic characters, for instance). Unlike user passwords, the +password from which the AFS key is derived can be longer than eight +characters, because it is never used during login. The kas +setpassword command accepts a password hundreds of characters +long. For instructions, see Managing Server Encryption Keys. +
As much as possible, limit the number of people who can login at a server +machine's console or remotely. Imposing this limit is an extra +security precaution rather than a necessity. The machine cannot serve +as an AFS client in this case. +
Particularly limit access to the local superuser root account +on a server machine. The local superuser root has free +access to important administrative subdirectories of the /usr/afs +directory, as described in AFS Files on the Local Disk. + +
As in any computing environment, server machines must be located in a +secured area. Any other security measures are effectively worthless if +unauthorized people can access the computer hardware. +

System Administrators +

Limit the number of system administrators in your cell. Limit the +use of system administrator accounts on publicly accessible +workstations. Such machines are not secure, so unscrupulous users can +install programs that try to steal tokens or passwords. If +administrators must use publicly accessible workstations at times, they must +issue the unlog command before leaving the machine. +
Create an administrative account for each administrator separate from the +personal account, and assign AFS privileges only to the administrative +account. The administrators must authenticate to the administrative +accounts to perform duties that require privilege, which provides a useful +audit trail as well. +
Administrators must not leave a machine unattended while they have valid +tokens. Issue the unlog command before leaving. +
Use the -lifetime argument to the kas setfields +command to set the token lifetime for administrative accounts to a fairly +short amount of time. The default lifetime for AFS tokens is 25 hours, +but 30 or 60 minutes is possibly a more reasonable lifetime for administrative +tokens. The tokens for administrators who initiate AFS Backup System +operations must last somewhat longer, because it can take several hours to +complete some dump operations, depending on the speed of the tape device and +the network connecting it to the file server machines that house the volumes +is it accessing. +
Limit administrators' use of the telnet program. It +sends unencrypted passwords across the network. Similarly, limit use of +other remote programs such as rsh and rcp, which send +unencrypted tokens across the network. +

+ + + + +

A More Detailed Look at Mutual Authentication

As in any file system, security is a prime concern in +AFS. A file system that makes file sharing easy is not useful if it +makes file sharing mandatory, so AFS incorporates several features that +prevent unauthorized users from accessing data. Security in a networked +environment is difficult because almost all procedures require transmission of +information across wires that almost anyone can tap into. Also, many +machines on networks are powerful enough that unscrupulous users can monitor +transactions or even intercept transmissions and fake the identity of one of +the participants. +

The most effective precaution against eavesdropping and information theft +or fakery is for servers and clients to accept the claimed identity of the +other party only with sufficient proof. In other words, the nature of +the network forces all parties on the network to assume that the other party +in a transaction is not genuine until proven so. Mutual +authentication is the means through which parties prove their +genuineness. +

Because the measures needed to prevent fakery must be quite sophisticated, +the implementation of mutual authentication procedures is complex. The +underlying concept is simple, however: parties prove their identities by +demonstrating knowledge of a shared secret. A shared secret +is a piece of information known only to the parties who are mutually +authenticating (they can sometimes learn it in the first place from a trusted +third party or some other source). The party who originates the +transaction presents the shared secret and refuses to accept the other party +as valid until it shows that it knows the secret too. +

The most common form of shared secret in AFS transactions is the +encryption key, also referred to simply as a key. +The two parties use their shared key to encrypt the packets of information +they send and to decrypt the ones they receive. Encryption using keys +actually serves two related purposes. First, it protects messages as +they cross the network, preventing anyone who does not know the key from +eavesdropping. Second, ability to encrypt and decrypt messages +successfully indicates that the parties are using the key (it is their shared +secret). If they are using different keys, messages remain scrambled +and unintelligible after decryption. +

The following sections describe AFS's mutual authentication procedures +in more detail. Feel free to skip these sections if you are not +interested in the mutual authentication process. +

Simple Mutual Authentication

Simple mutual authentication involves only one encryption key and two +parties, generally a client and server. The client contacts the server +by sending a challenge message encrypted with a key known only to +the two of them. The server decrypts the message using its key, which +is the same as the client's if they really do share the same +secret. The server responds to the challenge and uses its key to +encrypt its response. The client uses its key to decrypt the +server's response, and if it is correct, then the client can be sure that +the server is genuine: only someone who knows the same key as the client +can decrypt the challenge and answer it correctly. On its side, the +server concludes that the client is genuine because the challenge message made +sense when the server decrypted it. +

AFS uses simple mutual authentication to verify user identities during the +first part of the login procedure. In that case, the key is based on +the user's password. +

Complex Mutual Authentication

Complex mutual authentication involves three encryption keys +and three parties. All secure AFS transactions (except the first part +of the login process) employ complex mutual authentication. + + + +

When a client wishes to communicate with a server, it first contacts a +third party called a ticket-granter. The ticket-granter and +the client mutually authenticate using the simple procedure. When they +finish, the ticket-granter gives the client a server ticket (or +simply ticket) as proof that it (the ticket-granter) has +preverified the identity of the client. The ticket-granter encrypts the +ticket with the first of the three keys, called the server encryption +key because it is known only to the ticket-granter and the server the +client wants to contact. The client does not know this key. +

The ticket-granter sends several other pieces of information along with the +ticket. They enable the client to use the ticket effectively despite +being unable to decrypt the ticket itself. Along with the ticket, the +items constitute a token: +

A session key, which is the second encryption key involved in +mutual authentication. The ticket-granter invents the session key at +random as the shared secret between client and server. For reasons +explained further below, the ticket-granter also puts a copy of the session +key inside the ticket. The client and server use the session key to +encrypt messages they send to one another during their transactions. +The ticket-granter invents a different session key for each connection between +a client and a server (there can be several transactions during a single +connection). +
The name of the server for which the ticket is valid (and so which server +encryption key encrypts the ticket itself). +
A ticket lifetime indicator. The default lifetime of AFS server +tickets is 100 hours. If the client wants to contact the server again +after the ticket expires, it must contact the ticket-granter to get a new +ticket. +

The ticket-granter seals the entire token with the third key involved in +complex mutual authentication--the key known only to it (the +ticket-granter) and the client. In some cases, this third key is +derived from the password of the human user whom the client represents. +

Now that the client has a valid server ticket, it is ready to contact the +server. It sends the server two things: +

The server ticket. This is encrypted with the server encryption +key. +
Its request message, encrypted with the session key. Encrypting the +message protects it as it crosses the network, since only the server/client +pair for whom the ticket-granter invented the session key know it. +

At this point, the server does not know the session key, because the +ticket-granter just created it. However, the ticket-granter put a copy +of the session key inside the ticket. The server uses the server +encryption key to decrypts the ticket and learns the session key. It +then uses the session key to decrypt the client's request message. +It generates a response and sends it to the client. It encrypts the +response with the session key to protect it as it crosses the network. +

This step is the heart of mutual authentication between client and server, +because it proves to both parties that they know the same secret: +

The server concludes that the client is authorized to make a request +because the request message makes sense when the server decrypts it using the +session key. If the client uses a different session key than the one +the server finds inside the ticket, then the request message remains +unintelligible even after decryption. The two copies of the session key +(the one inside the ticket and the one the client used) can only be the same +if they both came from the ticket-granter. The client cannot fake +knowledge of the session key because it cannot look inside the ticket, sealed +as it is with the server encryption key known only to the server and the +ticket-granter. The server trusts the ticket-granter to give tokens +only to clients with whom it (the ticket-granter) has authenticated, so the +server decides the client is legitimate. +
(Note that there is no direct communication between the ticket-granter and +the server, even though their relationship is central to ticket-based mutual +authentication. They interact only indirectly, via the client's +possession of a ticket sealed with their shared secret.) +
The client concludes that the server is genuine and trusts the response it +gets back from the server, because the response makes sense after the client +decrypts it using the session key. This indicates that the server +encrypted the response with the same session key as the client knows. +The only way for the server to learn that matching session key is to decrypt +the ticket first. The server can only decrypt the ticket because it +shares the secret of the server encryption key with the ticket-granter. +The client trusts the ticket-granter to give out tickets only for legitimate +servers, so the client accepts a server that can decrypt the ticket as +genuine, and accepts its response. +

Backing Up AFS Data

AFS provides two related facilities that help the +administrator back up AFS data: backup volumes and the AFS Backup +System. +

Backup Volumes

The first facility is the backup volume, which you create by cloning a +read/write volume. The backup volume is read-only and so preserves the +state of the read/write volume at the time the clone is made. +

Backup volumes can ease administration if you mount them in the file system +and make their contents available to users. For example, it often makes +sense to mount the backup version of each user volume as a subdirectory of the +user's home directory. A conventional name for this mount point is +OldFiles. Create a new version of the backup volume (that +is, reclone the read/write) once a day to capture any changes that were made +since the previous backup. If a user accidentally removes or changes +data, the user can restore it from the backup volume, rather than having to +ask you to restore it. +

The IBM AFS User Guide does not mention backup volumes, so +regular users do not know about them if you decide not to use them. +This implies that if you do make backup versions of user volumes, +you need to tell your users about how the backup works and where you have +mounted it. +

Users are often concerned that the data in a backup volume counts against +their volume quota and some of them even want to remove the +OldFiles mount point. It does not, because the backup volume +is a separate volume. The only amount of space it uses in the +user's volume is the amount needed for the mount point, which is about +the same as the amount needed for a standard directory element. +

Backup volumes are discussed in detail in Creating Backup Volumes. +

The AFS Backup System

Backup volumes can reduce restoration requests, but they reside on disk +and so do not protect data from loss due to hardware failure. Like any +file system, AFS is vulnerable to this sort of data loss. +

To protect your cell's users from permanent loss of data, you are +strongly urged to back up your file system to tape on a regular and frequent +schedule. The AFS Backup System is available to ease the administration +and performance of backups. For detailed information about the AFS +Backup System, see Configuring the AFS Backup System and Backing Up and Restoring AFS Data. + + + + + + + + + + + + +

Using UNIX Remote Services in the AFS Environment

The AFS distribution includes modified versions of several +standard UNIX commands, daemons and programs that provide remote services, +including the following: +

The ftpd program +
The inetd daemon +
The rcp program +
The rlogind daemon +
The rsh command +

These modifications enable the commands to handle AFS authentication +information (tokens). This enables issuers to be recognized on the +remote machine as an authenticated AFS user. +

Replacing the standard versions of these programs in your file tree with +the AFS-modified versions is optional. It is likely that AFS's +transparent access reduces the need for some of the programs anyway, +especially those involved in transferring files from machine to machine, like +the ftpd and rcp programs. +

If you decide to use the AFS versions of these commands, be aware that +several of them are interdependent. For example, the passing of AFS +authentication information works correctly with the rcp command +only if you are using the AFS version of both the rcp and +inetd commands. +

The conventional installation location for the modified remote commands are +the /usr/afsws/bin and /usr/afsws/etc +directories. To learn more about commands' functionality, see +their reference pages in the IBM AFS Administration +Reference. +

Accessing AFS through NFS

Users of NFS client machines can access the AFS filespace by +mounting the /afs directory of an AFS client machine that is +running the NFS/AFS Translator. This is a particular +advantage in cells already running NFS who want to access AFS using client +machines for which AFS is not available. See Appendix A, Managing the NFS/AFS Translator. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd008.htm b/doc/html/AdminGuide/auagd008.htm new file mode 100644 index 0000000..7908faa --- /dev/null +++ b/doc/html/AdminGuide/auagd008.htm @@ -0,0 +1,2713 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

+ + +

Administering Server Machines

This chapter describes how to administer an AFS server +machine. It describes the following configuration information and +administrative tasks: +

The binary and configuration files that must reside in the subdirectories +of the /usr/afs directory on every server machine's local +disk; see Local Disk Files on a Server Machine. +
The various roles or functions that an AFS server machine can +perform, and how to determine which machines are taking a role; see The Four Roles for File Server Machines. +
How to maintain database server machines; see Administering Database Server Machines. +
How to maintain the list of database server machines in the +/usr/afs/etc/CellServDB file; see Maintaining the Server CellServDB File. +
How to control authorization checking on a server machine; see Managing Authentication and Authorization Requirements. +
How to install new disks or partitions on a file server machine; see Adding or Removing Disks and Partitions. +
How to change a server machine's IP addresses and manager VLDB server +entries; see Managing Server IP Addresses and VLDB Server Entries. +
How to reboot a file server machine; see Rebooting a Server Machine. +

To learn how to install and configure a new server machine, see the +IBM AFS Quick Beginnings. +

To learn how to administer the server processes themselves, see Monitoring and Controlling Server Processes. +

To learn how to administer volumes, see Managing Volumes. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + + + + + + + + + + + + + +
Install new binaries + bos install +
Examine binary check-and-restart time + bos getrestart +
Set binary check-and-restart time + bos setrestart +
Examine compilation dates on binary files + bos getdate +
Restart a process to use new binaries + bos restart +
Revert to old version of binaries + bos uninstall +
Remove obsolete .BAK and .OLD +versions + bos prune +
List partitions on a file server machine + vos listpart +
Shutdown AFS server processes + bos shutdown +
List volumes on a partition + vos listvldb +
Move read/write volumes + vos move +
List a cell's database server machines + bos listhosts +
Add a database server machine to server CellServDB file + bos addhost +
Remove a database server machine from server CellServDB file + bos removehost +
Set authorization checking requirements + bos setauth +
Prevent authentication for bos, pts, and +vos commands + Include -noauth flag +
Prevent authentication for kas commands + Include -noauth flag on some commands or issue +noauthentication while in interactive mode +
Display all VLDB server entries + vos listaddrs +
Remove a VLDB server entry + vos changeaddr +
Reboot a server machine remotely + bos exec reboot_command +
+

Local Disk Files on a Server Machine

Several types of files must reside in the subdirectories of +the /usr/afs directory on an AFS server machine's local +disk. They include binaries, configuration files, the administrative +database files (on database server machines), log files, and volume header +files. +

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. + + + +

Binaries in the /usr/afs/bin Directory

The /usr/afs/bin directory stores the AFS server +process and command suite binaries appropriate for the machine's system +(CPU and operating system) type. If a process has both a server portion +and a client portion (as with the Update Server) or if it has separate +components (as with the fs process), each component resides in a +separate file. +

To ensure predictable system performance, all file server machines must run +the same AFS build version of a given process. To maintain consistency +easily, use the Update Server process to distribute binaries from a +binary distribution machine of each system type, as described +further in Binary Distribution Machines. +

It is best to keep the binaries for all processes in the +/usr/afs/bin directory, even if you do not run the process actively +on the machine. It simplifies the process of reconfiguring machines +(for example, adding database server functionality to an existing file server +machine). Similarly, it is best to keep the command suite binaries in +the directory, even if you do not often issue commands while working on the +server machine. It enables you to issue commands during recovery from +server and machine outages. +

The following lists the binary files in the /usr/afs/bin +directory that are directly related to the AFS server processes or command +suites. Other binaries (for example, for the klog command) +sometimes appear in this directory on a particular file server machine's +disk or in an AFS distribution. +

backup +: The command suite for the AFS Backup System (the binary for the Backup +Server is buserver). + + +
bos +: The command suite for communicating with the Basic OverSeer (BOS) Server +(the binary for the BOS Server is bosserver). + + + + + + +
bosserver +: The binary for the Basic OverSeer (BOS) Server process. + + + + + + +
buserver +: The binary for the Backup Server process. + + + + + + +
fileserver +: The binary for the File Server component of the fs +process. + + +
kas +: The command suite for communicating with the Authentication Server (the +binary for the Authentication Server is kaserver). + + + + + + +
kaserver +: The binary for the Authentication Server process. + + + + + + +
ntpd +: The binary for the Network Time Protocol Daemon (NTPD). AFS +redistributes this binary and uses the runntp program to configure +and initialize the NTPD process. + + + +
ntpdc +: A debugging utility furnished with the ntpd program. + + +
pts +: The command suite for communicating with the Protection Server process +(the binary for the Protection Server is ptserver). + + + + + + +
ptserver +: The binary for the Protection Server process. + + + + +
runntp +: The binary for the program used to configure NTPD most appropriately for +use with AFS. + + + + + + +
salvager +: The binary for the Salvager component of the fs process. + + + + +
udebug +: The binary for a program that reports the status of AFS's distributed +database technology, Ubik. + + + + + + +
upclient +: The binary for the client portion of the Update Server process. + + + + +
upserver +: The binary for the server portion of the Update Server process. + + + + + + + +
vlserver +: The binary for the Volume Location (VL) Server process. + + + + + + +
volserver +: The binary for the Volume Server component of the fs +process. + + +
vos +: The command suite for communicating with the Volume and VL Server +processes (the binaries for the servers are volserver and +vlserver, respectively). +

+ + + + + +

Common Configuration Files in the /usr/afs/etc Directory

The directory /usr/afs/etc on every file server +machine's local disk contains configuration files in ASCII and +machine-independent binary format. For predictable AFS performance +throughout a cell, all server machines must have the same version of each +configuration file: +

Cells that run the United States edition of AFS conventionally use the +Update Server to distribute a common version of each file from the cell's +system control machine to other server machines (for more on the system +control machine, see The System Control Machine). Run the Update Server's server portion on the +system control machine, and the client portion on all other server +machines. Update the files on the system control machine only, except +as directed by instructions for dealing with emergencies. +
Cells that run the international edition of AFS must not use the Update +Server to distribute the contents of the /usr/afs/etc +directory. Due to United States government regulations, the data +encryption routines that AFS uses to protect the files in this directory as +they cross the network are not available to the Update Server in the +international edition of AFS. You must instead update the files on each +server machine individually, taking extra care to issue exactly the same +bos command for each machine. The necessary data encryption +routines are available to the bos commands, so information is safe +as it crosses the network from the machine where the bos command is +issued to the server machines. +

Never directly edit any of the files in the /usr/afs/etc +directory, except as directed by instructions for dealing with +emergencies. In normal circumstances, use the appropriate +bos commands to change the files. The following list +includes pointers to instructions. +

The files in this directory include: +

CellServDB +

An ASCII file that names the cell's database server machines, which +run the Authentication, Backup, Protection, and VL Server processes. +You create the initial version of this file by issuing the bos +setcellname command while installing your cell's first server +machine. It is very important to update this file when you change the +identity of your cell's database server machines. +

The server CellServDB file is not the same as the +CellServDB file stored in the /usr/vice/etc directory on +client machines. The client version lists the database server machines +for every AFS cell that you choose to make accessible from the client +machine. The server CellServDB file lists only the local +cell's database server machines, because server processes never contact +processes in other cells. +

For instructions on maintaining this file, see Maintaining the Server CellServDB File. + + + +

KeyFile +

A machine-independent, binary-format file that lists the server encryption +keys the AFS server processes use to encrypt and decrypt tickets. The +information in this file is the basis for secure communication in the cell, +and so is extremely sensitive. The file is specially protected so that +only privileged users can read or change it. +

For instructions on maintaining this file, see Managing Server Encryption Keys. + + +

ThisCell +

An ASCII file that consists of a single line defining the complete +Internet domain-style name of the cell (such as +abc.com). You create this file with the bos +setcellname command during the installation of your cell's first +file server machine, as instructed in the IBM AFS Quick +Beginnings. +

Note that changing this file is only one step in changing your cell's +name. For discussion, see Choosing a Cell Name. + + +

UserList +

An ASCII file that lists the usernames of the system administrators +authorized to issue privileged bos, vos, and +backup commands. For instructions on maintaining the file, +see Administering the UserList File. +

+ + + + +

Local Configuration Files in the /usr/afs/local Directory

The directory /usr/afs/local contains +configuration files that are different for each file server machine in a +cell. Thus, they are not updated automatically from a central source +like the files in /usr/afs/bin and /usr/afs/etc +directories. The most important file is the BosConfig +file; it defines which server processes are to run on that +machine. +

As with the common configuration files in /usr/afs/etc, you must +not edit these files directly. Use commands from the bos +command suite where appropriate; some files never need to be +altered. +

The files in this directory include the following: +

BosConfig +

This file lists the server processes to run on the server machine, by +defining which processes the BOS Server monitors and what it does if the +process fails. It also defines the times at which the BOS Server +automatically restarts processes for maintenance purposes. +

As you create server processes during a file server machine's +installation, their entries are defined in this file automatically. The +IBM AFS Quick Beginnings outlines the bos commands to +use. For a more complete description of the file, and instructions for +controlling process status by editing the file with commands from the +bos suite, see Monitoring and Controlling Server Processes. + + +

NetInfo +

This optional ASCII file lists one or more of the network interface +addresses on the server machine. If it exists when the File Server +initializes, the File Server uses it as the basis for the list of interfaces +that it registers in its Volume Location Database (VLDB) server entry. +See Managing Server IP Addresses and VLDB Server Entries. + + +

NetRestrict +

This optional ASCII file lists one or more network interface +addresses. If it exists when the File Server initializes, the File +Server removes the specified addresses from the list of interfaces that it +registers in its VLDB server entry. See Managing Server IP Addresses and VLDB Server Entries. + + +

NoAuth +

This zero-length file instructs all AFS server processes running on the +machine not to perform authorization checking. Thus, they perform any +action for any user, even anonymous. This very insecure +state is useful only in rare instances, mainly during the installation of the +machine. +

The file is created automatically when you start the initial +bosserver process with the -noauth flag, or issue the +bos setauth command to turn off authentication requirements. +When you use the bos setauth command to turn on authentication, the +BOS Server removes this file. For more information, see Managing Authentication and Authorization Requirements. + + +

SALVAGE.fs +

This zero-length file controls how the BOS Server handles a crash of the +File Server component of the fs process. The BOS Server +creates this file each time it starts or restarts the fs +process. If the file is present when the File Server crashes, then the +BOS Server runs the Salvager before restarting the File Server and Volume +Server again. When the File Server exits normally, the BOS Server +removes the file so that the Salvager does not run. +

Do not create or remove this file yourself; the BOS Server does so +automatically. If necessary, you can salvage a volume or partition by +using the bos salvage command; see Salvaging Volumes. + + +

salvage.lock +

This file guarantees that only one Salvager process runs on a file server +machine at a time (the single process can fork multiple subprocesses to +salvage multiple partitions in parallel). As the Salvager initiates +(when invoked by the BOS Server or by issue of the bos salvage +command), it creates this zero-length file and issues the flock +system call on it. It removes the file when it completes the salvage +operation. Because the Salvager must lock the file in order to run, +only one Salvager can run at a time. + + + + +

sysid +

This file records the network interface addresses that the File Server +(fileserver process) registers in its VLDB server entry. +When the Cache Manager requests volume location information, the Volume +Location (VL) Server provides all of the interfaces registered for each server +machine that houses the volume. This enables the Cache Manager to make +use of multiple addresses when accessing AFS data stored on a multihomed file +server machine. For further information, see Managing Server IP Addresses and VLDB Server Entries. +

+ + + + + + +

Replicated Database Files in the /usr/afs/db Directory

The directory /usr/afs/db contains two types of +files pertaining to the four replicated databases in the cell--the +Authentication Database, Backup Database, Protection Database, and Volume +Location Database (VLDB): +

A file that contains each database, with a .DB0 +extension. +
A log file for each database, with a .DBSYS1 +extension. The database server process logs each database operation in +this file before performing it. If the operation is interrupted, the +process consults this file to learn how to finish it. +

Each database server process (Authentication, Backup, Protection, or VL +Server) maintains its own database and log files. The database files +are in binary format, so you must always access or alter them using commands +from the kas suite (for the Authentication Database), +backup suite (for the Backup Database), pts suite (for +the Protection Database), or vos suite (for the VLDB). +

If a cell runs more than one database server machine, each database server +process keeps its own copy of its database on its machine's hard +disk. However, it is important that all the copies of a given database +are the same. To synchronize them, the database server processes call +on AFS's distributed database technology, Ubik, as described in Replicating the AFS Administrative Databases. +

The files listed here appear in this directory only on database server +machines. On non-database server machines, this directory is +empty. +

bdb.DB0 +: The Backup Database file. + + +
bdb.DBSYS1 +: The Backup Database log file. + + +
kaserver.DB0 +: The Authentication Database file. + + +
kaserver.DBSYS1 +: The Authentication Database log file. + + +
prdb.DB0 +: The Protection Database file. + + +
prdb.DBSYS1 +: The Protection Database log file. + + +
vldb.DB0 +: The Volume Location Database file. + + +
vldb.DBSYS1 +: The Volume Location Database log file. +

+ + + + + + +

Log Files in the /usr/afs/logs Directory

The /usr/afs/logs directory contains log files +from various server processes. The files detail interesting events that +occur during normal operations. For instance, the Volume Server can +record volume moves in the VolserLog file. Events are +recorded at completion, so the server processes do not use these files to +reconstruct failed operations unlike the ones in the /usr/afs/db +directory. +

The information in log files can be very useful as you evaluate process +failures and other problems. For instance, if you receive a timeout +message when you try to access a volume, checking the FileLog file +possibly provides an explanation, showing that the File Server was unable to +attach the volume. To examine a log file remotely, use the bos +getlog command as described in Displaying Server Process Log Files. +

This directory also contains the core image files generated if a process +being monitored by the BOS Server crashes. The BOS Server attempts to +add an extension to the standard core name to indicate which +process generated the core file (for example, naming a core file generated by +the Protection Server core.ptserver). The BOS Server +cannot always assign the correct extension if two processes fail at about the +same time, so it is not guaranteed to be correct. +

The directory contains the following files: +

AuthLog +: The Authentication Server's log file. + + +
BackupLog +: The Backup Server's log file. + + +
BosLog +: The BOS Server's log file. + + +
FileLog +: The File Server's log file. + + +
SalvageLog +: The Salvager's log file. + + +
VLLog +: The Volume Location (VL) Server's log file. + + +
VolserLog +: The Volume Server's log file. +
core.process +: If present, a core image file produced as an AFS server process on the +machine crashed (probably the process named by process). +

Note:

To prevent log files from growing unmanageably large, restart the server +processes periodically, particularly the database server processes. To +avoid restarting the processes, use the UNIX rm command to remove +the file as the process runs; it re-creates it automatically. +

+ + + + + +

Volume Headers on Server Partitions

A partition that houses AFS volumes must be mounted at a +subdirectory of the machine's root ( / ) directory (not, for instance +under the /usr directory). The file server machine's +file system registry file (/etc/fstab or equivalent) must correctly +map the directory name and the partition's device name. The +directory name is of the form /vicepindex, where each +index is one or two lowercase letters. By convention, the +first AFS partition on a machine is mounted at /vicepa, the second +at /vicepb, and so on. If there are more than 26 partitions, +continue with /vicepaa, /vicepab and so on. The +IBM AFS Release Notes specifies the number of supported partitions +per server machine. +

Do not store non-AFS files on AFS partitions. The File Server and +Volume Server expect to have available all of the space on the +partition. +

The /vicep directories contain two types of files: +

Vvol_ID.vol +: Each such file is a volume header. The vol_ID corresponds +to the volume ID number displayed in the output from the vos +examine, vos listvldb, and vos listvol +commands. + + +
FORCESALVAGE +: This zero-length file triggers the Salvager to salvage the entire +partition. The AFS-modified version of the fsck program +creates this file if it discovers corruption. +

Note:

For most system types, it is important never to run the standard +fsck program provided with the operating system on an AFS file +server machine. It removes all AFS volume data from server partitions +because it does not recognize their format. +

+ + +

The Four Roles for File Server Machines

In cells that have more than one server machine, not all +server machines have to perform exactly the same functions. The are +four possible roles a machine can assume, determined by which +server processes it is running. A machine can assume more than one role +by running all of the relevant processes. The following list summarizes +the four roles, which are described more completely in subsequent +sections. +

A simple file server machine runs only the processes that store +and deliver AFS files to client machines. You can run as many simple +file server machines as you need to satisfy your cell's performance and +disk space requirements. +
A database server machine runs the four database server +processes that maintain AFS's replicated administrative databases: +the Authentication, Backup, Protection, and Volume Location (VL) Server +processes. +
A binary distribution machine distributes the AFS server +binaries for its system type to all other server machines of that system +type. +
The single system control machine distributes common server +configuration files to all other server machines in the cell, in a cell that +runs the United States edition of AFS (cells that use the international +edition of AFS must not use the system control machine for this +purpose). The machine conventionally also serves as the time +synchronization source for the cell, adjusting its clock according to a time +source outside the cell. +

If a cell has a single server machine, it assumes the simple file server +and database server roles. The instructions in the IBM AFS Quick +Beginnings also have you configure it as the system control machine and +binary distribution machine for its system type, but it does not actually +perform those functions until you install another server machine. +

It is best to keep the binaries for all of the AFS server processes in the +/usr/afs/bin directory, even if not all processes are +running. You can then change which roles a machine assumes simply by +starting or stopping the processes that define the role. + + +

Simple File Server Machines

A simple file server machine runs only the server +processes that store and deliver AFS files to client machines, monitor process +status, and pick up binaries and configuration files from the cell's +binary distribution and system control machines. +

In general, only cells with more than three server machines need to run +simple file server machines. In cells with three or fewer machines, all +of them are usually database server machines (to benefit from replicating the +administrative databases); see Database Server Machines. +

The following processes run on a simple file server machine: +

The BOS Server (bosserver process) +
The fs process, which combines the File Server, Volume Server, +and Salvager processes so that they can coordinate their operations on the +data in volumes and avoid the inconsistencies that can result from multiple +simultaneous operations on the same data +
The NTP coordinator (runntp process), which helps keep the +machine's clock synchronized with the clocks on the other server machines +in the cell +
A client portion of the Update Server that picks up binary files from the +binary distribution machine of its AFS system type (the upclientbin +process) +
A client portion of the Update Server that picks up common configuration +files from the system control machine, in cells running the United States +edition of AFS (the upclientetc process) +

+ + + + + + +

Database Server Machines

A database server machine runs the four processes +that maintain the AFS replicated administrative databases: the +Authentication Server, Backup Server, Protection Server, and Volume Location +(VL) Server, which maintain the Authentication Database, Backup Database, +Protection Database, and Volume Location Database (VLDB), respectively. +To review the functions of these server processes and their databases, see AFS Server Processes and the Cache Manager. +

If a cell has more than one server machine, it is best to run more than one +database server machine, but more than three are rarely necessary. +Replicating the databases in this way yields the same benefits as replicating +volumes: increased availability and reliability of information. +If one database server machine or process goes down, the information in the +database is still available from others. The load of requests for +database information is spread across multiple machines, preventing any one +from becoming overloaded. +

Unlike replicated volumes, however, replicated databases do change +frequently. Consistent system performance demands that all copies of +the database always be identical, so it is not possible to record changes in +only some of them. To synchronize the copies of a database, the +database server processes use AFS's distributed database technology, +Ubik. See Replicating the AFS Administrative Databases. +

It is critical that the AFS server processes on every server machine in a +cell know which machines are the database server machines. The database +server processes in particular must maintain constant contact with their peers +in order to coordinate the copies of the database. The other server +processes often need information from the databases. Every file server +machine keeps a list of its cell's database server machines in its local +/usr/afs/etc/CellServDB file. Cells that use the States +edition of AFS can use the system control machine to distribute this file (see +The System Control Machine). +

The following processes define a database server machine: +

The Authentication Server (kaserver process) +
The Backup Server (buserver process) +
The Protection Server (ptserver process) +
The VL Server (vlserver process) +

Database server machines can also run the processes that define a simple +file server machine, as listed in Simple File Server Machines. One database server machine can act as the +cell's system control machine, and any database server machine can serve +as the binary distribution machine for its system type; see The System Control Machine and Binary Distribution Machines. + + + + +

Binary Distribution Machines

A binary distribution machine stores and +distributes the binary files for the AFS processes and command suites to all +other server machines of its system type. Each file server machine +keeps its own copy of AFS server process binaries on its local disk, by +convention in the /usr/afs/bin directory. For consistent +system performance, however, all server machines must run the same version +(build level) of a process. For instructions for checking a +binary's build level, see Displaying A Binary File's Build Level. The easiest way to keep the binaries +consistent is to have a binary distribution machine of each system type +distribute them to its system-type peers. +

The process that defines a binary distribution machine is the server +portion of the Update Server (upserver process). The client +portion of the Update Server (upclientbin process) runs on the +other server machines of that system type and references the binary +distribution machine. +

Binary distribution machines usually also run the processes that define a +simple file server machine, as listed in Simple File Server Machines. One binary distribution machine can act as the +cell's system control machine, and any binary distribution machine can +serve as a database server machine; see The System Control Machine and Database Server Machines. + + + +

The System Control Machine

In cells that run the United States edition of AFS, the +system control machine stores and distributes system configuration +files shared by all of the server machines in the cell. Each file +server machine keeps its own copy of the configuration files on its local +disk, by convention in the /usr/afs/etc directory. For +consistent system performance, however, all server machines must use the same +files. The easiest way to keep the files consistent is to have the +system control machine distribute them. You make changes only to the +copy stored on the system control machine, as directed by the instructions in +this document. The United States edition of AFS is available to cells +in the United States and Canada and to selected institutions in other +countries, as determined by United States government regulations. +

Cells that run the international version of AFS do not use the system +control machine to distribute system configuration files. Some of the +files contain information that is too sensitive to cross the network +unencrypted, and United States government regulations forbid the export of the +necessary encryption routines in the form that the Update Server uses. +You must instead update the configuration files on each file server machine +individually. The bos commands that you use to update the +files encrypt the information using an exportable form of the encryption +routines. +

For a list of the configuration files stored in the /usr/afs/etc +directory, see Common Configuration Files in the /usr/afs/etc Directory. +

The IBM AFS Quick Beginnings configures a cell's first +server machine as the system control machine. If you wish, you can +reassign the role to a different machine that you install later, but you must +then change the client portion of the Update Server (upclientetc) +process running on all other server machines to refer to the new system +control machine. +

The following processes define the system control machine: +

The server portion of the Update Server (upserver) process, in +cells using the United States edition of AFS. The client portion of the +Update Server (upclientetc process) runs on the other server +machines and references the system control machine. +
The NTP coordinator (runntp process) which points to a time +source outside the cell, if the cell uses NTPD to synchronize its +clocks. The runntp process on other machines reference the +system control machine as their main time source. +

The system control machine can also run the processes that define a simple +file server machine, as listed in Simple File Server Machines. It can also server as a database server machine, and +by convention acts as the binary distribution machine for its system +type. A single upserver process can distribute both +configuration files and binaries. See Database Server Machines and Binary Distribution Machines. + + + + + + + +

To locate database server machines

Issue the bos listhosts command. +
```
   % bos listhosts <machine name>
+
```
+
The machines listed in the output are the cell's database server +machines. For complete instructions and example output, see To display a cell's database server machines. +
(Optional) Issue the bos status command to verify +that a machine listed in the output of the bos listhosts command is +actually running the processes that define it as a database server +machine. For complete instructions, see Displaying Process Status and Information from the BosConfig File. +
```
   % bos status <machine name> buserver kaserver ptserver vlserver
+
```
+
If the specified machine is a database server machine, the output from the + bos status command includes the following lines: +
```
   Instance buserver, currently running normally.
+   Instance kaserver, currently running normally.
+   Instance ptserver, currently running normally.
+   Instance vlserver, currently running normally.
+
```
+

+ + + +

To locate the system control machine

Issue the bos status command for any server machine. +Complete instructions appear in Displaying Process Status and Information from the BosConfig File. +
```
   % bos status <machine name> upserver upclientbin upclientetc -long
+
```
+
The output you see depends on the machine you have contacted: a +simple file server machine, the system control machine, or a binary +distribution machine. See Interpreting the Output from the bos status Command. +

+ + + +

To locate the binary distribution machine for a system type

Issue the bos status command for a file server machine of the +system type you are checking (to determine a machine's system type, issue +the fs sysname or sys command as described in Displaying and Setting the System Type Name. Complete instructions for the bos status +command appear in Displaying Process Status and Information from the BosConfig File. +
```
   % bos status <machine name> upserver upclientbin upclientetc -long
+
```
+
The output you see depends on the machine you have contacted: a +simple file server machine, the system control machine, or a binary +distribution machine. See Interpreting the Output from the bos status Command. +

+ + + +

Interpreting the Output from the bos status Command

Interpreting the output of the bos status command +is most straightforward for a simple file server machine. There is no +upserver process, so the output includes the following +message: +

   bos: failed to get instance info for 'upserver' (no such entity)
+

A simple file server machine runs the upclientbin process, so +the output includes a message like the following. It indicates that +fs7.abc.com is the binary distribution machine for +this system type. +

   Instance upclientbin, (type is simple) currently running normally.
+   Process last started at Wed Mar 10  23:37:09 1999 (1 proc start)
+   Command 1 is '/usr/afs/bin/upclient fs7.abc.com -t 60 /usr/afs/bin'
+

If you run the United States edition of AFS, a simple file server machine +also runs the upclientetc process, so the output includes a message +like the following. It indicates that +fs1.abc.com is the system control machine. +

   Instance upclientetc, (type is simple) currently running normally.
+   Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
+   Command 1 is '/usr/afs/bin/upclient fs1.abc.com -t 60 /usr/afs/etc'
+

The Output on the System Control Machine

If you run the United States edition of AFS and have issued +the bos status command for the system control machine, the output +includes an entry for the upserver process similar to the +following: +

   Instance upserver, (type is simple) currently running normally.
+   Process last started at Mon Mar 22 05:23:54 1999 (1 proc start)
+   Command 1 is '/usr/afs/bin/upserver'
+

If you are using the default configuration recommended in the IBM AFS +Quick Beginnings, the system control machine is also the binary +distribution machine for its system type, and a single upserver +process distributes both kinds of updates. In that case, the output +includes the following messages: +

   bos: failed to get instance info for 'upclientbin' (no such entity)
+   bos: failed to get instance info for 'upclientetc' (no such entity)
+

If the system control machine is not a binary distribution machine, the +output includes an error message for the upclientetc process, but a +complete a listing for the upclientbin process (in this case it +refers to the machine fs5.abc.com as the binary +distribution machine): +

   Instance upclientbin, (type is simple) currently running normally.
+   Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
+   Command 1 is '/usr/afs/bin/upclient fs5.abc.com -t 60 /usr/afs/bin'
+   bos: failed to get instance info for 'upclientetc' (no such entity)
+

The Output on a Binary Distribution Machine

If you have issued the bos status command for a +binary distribution machine, the output includes an entry for the +upserver process similar to the following and error message for the +upclientbin process: +

   Instance upserver, (type is simple) currently running normally.
+   Process last started at Mon Apr 5 05:23:54 1999 (1 proc start)
+   Command 1 is '/usr/afs/bin/upserver'
+   bos: failed to get instance info for 'upclientbin' (no such entity)
+

Unless this machine also happens to be the system control machine, a +message like the following references the system control machine (in this +case, fs3.abc.com): +

   Instance upclientetc, (type is simple) currently running normally.
+   Process last started at Mon Apr 5 05:23:49 1999 (1 proc start)
+   Command 1 is '/usr/afs/bin/upclient fs3.abc.com -t 60 /usr/afs/etc'
+

Administering Database Server Machines

This section explains how to administer database server +machines. For installation instructions, see the IBM AFS Quick +Beginnings. + + + + + + + + + + + +

Replicating the AFS Administrative Databases

There are several benefits to replicating the AFS +administrative databases (the Authentication, Backup, Protection, and Volume +Location Databases), as discussed in Replicating the AFS Administrative Databases. For correct cell functioning, the copies of each +database must be identical at all times. To keep the databases +synchronized, AFS uses library of utilities called Ubik. +Each database server process runs an associated lightweight Ubik process, and +client-side programs call Ubik's client-side subroutines when they submit +requests to read and change the databases. +

Ubik is designed to work with minimal administrator intervention, but there +are several configuration requirements, as detailed in Configuring the Cell for Proper Ubik Operation. The following brief overview of Ubik's +operation is helpful for understanding the requirements. For more +details, see How Ubik Operates Automatically. +

Ubik is designed to distribute changes made in an AFS administrative +database to all copies as quickly as possible. Only one copy of the +database, the synchronization site, accepts change requests from +clients; the lightweight Ubik process running there is the Ubik +coordinator. To maintain maximum availability, there is a +separate Ubik coordinator for each database, and the synchronization site for +each of the four databases can be on a different machine. The +synchronization site for a database can also move from machine to machine in +response to process, machine, or network outages. +

The other copies of a database, and the Ubik processes that maintain them, +are termed secondary. The secondary sites do not accept +database changes directly from client-side programs, but only from the +synchronization site. +

After the Ubik coordinator records a change in its copy of a database, it +immediately sends the change to the secondary sites. During the brief +distribution period, clients cannot access any of the copies of the database, +even for reading. If the coordinator cannot reach a majority of the +secondary sites, it halts the distribution and informs the client that the +attempted change failed. +

To avoid distribution failures, the Ubik processes maintain constant +contact by exchanging time-stamped messages. As long as a majority of +the secondary sites respond to the coordinator's messages, there is a +quorum of sites that are synchronized with the coordinator. +If a process, machine, or network outage breaks the quorum, the Ubik processes +attempt to elect a new coordinator in order to establish a new quorum among +the highest possible number of sites. See A Flexible Coordinator Boosts Availability. + + + +

Configuring the Cell for Proper Ubik Operation

This section describes how to configure your cell to +maintain proper Ubik operation. +

Run all four database server processes--Authentication Server, Backup +Server, Protection Server, and VL Server--on all database server +machines. +
Both the client and server portions of Ubik expect that all the database +server machines listed in the CellServDB file are running all of +the database server processes. There is no mechanism for indicating +that only some database server processes are running on a machine. +
Maintain correct information in the /usr/afs/etc/CellServDB +file at all times. +
Ubik consults the /usr/afs/etc/CellServDB file to determine the +sites with which to establish and maintain a quorum. Incorrect +information can result in unsynchronized databases or election of a +coordinator in each of several subgroups of machines, because the Ubik +processes on various machines do not agree on which machines need to +participate in the quorum. +
If you run the United States version of AFS and use the Update Server, it +is simplest to maintain the /usr/afs/etc/CellServDB file on the +system control machine, which distributes its copy to all other server +machines. The IBM AFS Quick Beginnings explains how to +configure the Update Server. If you run the international version of +AFS, you must update the file on each machine individually. +
The only reason to alter the file is when configuring or decommissioning a +database server machine. Use the appropriate bos commands +rather than editing the file by hand. For instructions, see Maintaining the Server CellServDB File. The instructions in Monitoring and Controlling Server Processes for stopping and starting processes remind +you to alter the CellServDB file when appropriate, as do the +instructions in the IBM AFS Quick Beginnings for installing or +decommissioning a database server machine. +
(Client processes and the server processes that do not maintain databases +also rely on correct information in the CellServDB file for proper +operation, but their use of the information does not affect Ubik's +operation. See Maintaining the Server CellServDB File and Maintaining Knowledge of Database Server Machines.) + +
Keep the clocks synchronized on all machines in the cell, especially the +database server machines. +
In the conventional configuration specified in the IBM AFS Quick +Beginnings, you run the runntp process to supervise the local +Network Time Protocol Daemon (NTPD) on every AFS server machine. The +NTPD on the system control machine synchronizes its clock with a reliable +source outside the cell and broadcasts the time to the NTPDs on the other +server machines. You can choose to run a different time synchronization +protocol if you wish. +
Keeping clocks synchronized is important because the Ubik processes at a +database's sites timestamp the messages which they exchange to maintain +constant contact. Timestamping the messages is necessary because in a +networked environment it is not safe to assume that a message reaches its +destination instantly. Ubik compares the timestamp on an incoming +message with the current time. If the difference is too great, it is +possible that an outage is preventing reliable communication between the Ubik +sites, which can possibly result in unsynchronized databases. Ubik +considers the message invalid, which can prompt it to attempt election of a +different coordinator. +
Electing a new coordinator is appropriate if a timestamped message is +expired due to actual interruption of communication, but not if a message +appears expired only because the sender and recipient do not share the same +time. For detailed examples of how unsynchronized clocks can +destabilize Ubik operation, see How Ubik Uses Timestamped Messages. +

+ + + +

How Ubik Operates Automatically

The following Ubik features help keep its maintenance +requirements to a minimum: +

Ubik's server and client portions operate automatically. +
Each database server process runs a lightweight process to call on the +server portion of the Ubik library. It is common to refer to this +lightweight process itself as Ubik. Because it is lightweight, the Ubik +process does not appear in process listings such as those generated by the +UNIX ps command. Client-side programs that need to read and +change the databases directly call the subroutines in the Ubik library's +client portion, rather than running a separate lightweight process. +Examples of such programs are the klog command and the commands in +the pts suite. +
Ubik tracks database version numbers. +
As the coordinator records a change to a database, it increments the +database's version number. The version number makes it easy for +the coordinator to determine if a site has the most recent version or +not. The version number speeds the return to normal functioning after +election of a new coordinator or when communication is restored after an +outage, because it makes it easy to determine which site has the most current +database and which need to be updated. +
Ubik's use of timestamped messages guarantees that database copies +are always synchronized during normal operation. +
Replicating a database to increase data availability is pointless if all +copies of the database are not the same. Inconsistent performance can +result if clients receive different information depending on which copy of the +database they access. As previously noted, Ubik sites constantly track +the status of their peers by exchanging timestamped messages. For a +detailed description, see How Ubik Uses Timestamped Messages. +
The ability to move the coordinator maximizes database +availability. +
Suppose, for example, that in a cell with three database server machines a +network partition separates the two secondary sites from the +coordinator. The coordinator retires because it is no longer in contact +with a majority of the sites listed in the CellServDB file. +The two sites on the other side of the partition can elect a new coordinator +among themselves, and it can then accept database changes from clients. +If the coordinator cannot move in this way, the database has to be read-only +until the network partition is repaired. For a detailed description of +Ubik's election procedure, see A Flexible Coordinator Boosts Availability. +

+ + +

How Ubik Uses Timestamped Messages

Ubik synchronizes the copies of a database by maintaining +constant contact between the synchronization site and the secondary +sites. The Ubik coordinator frequently sends a time-stamped +guarantee message to each of the secondary sites. When the +secondary site receives the message, it concludes that it is in contact with +the coordinator. It considers its copy of the database to be valid +until time T, which is usually 60 seconds from the time the +coordinator sent the message. In response, the secondary site returns a +vote message that acknowledges the coordinator as valid until a +certain time X, which is usually 120 seconds in the future. +

The coordinator sends guarantee messages more frequently than every +T seconds, so that the expiration periods overlap. There is +no danger of expiration unless a network partition or other outage actually +interrupts communication. If the guarantee expires, the secondary +site's copy of the database it not necessarily current. +Nonetheless, the database server continues to service client requests. +It is considered better for overall cell functioning that a secondary site +remains accessible even if the information it is distributing is possibly out +of date. Most of the AFS administrative databases do not change that +frequently, in any case, and making a database inaccessible causes a timeout +for clients that happen to access that copy. +

As previously mentioned, Ubik's use of timestamped messages makes it +vital to synchronize the clocks on database server machines. There are +two ways that skewed clocks can interrupt normal Ubik functioning, depending +on which clock is ahead of the others. +

Suppose, for example, that the Ubik coordinator's clock is ahead of +the secondary sites: the coordinator's clock says +9:35:30, but the secondary clocks say 9:31:30. +The secondary sites send votes messages that acknowledge the coordinator as +valid until 9:33:30. This is two minutes in the future +according to the secondary clocks, but is already in the past from the +coordinator's perspective. The coordinator concludes that it no +longer has enough support to remain coordinator and forces election of a new +coordinator. Election takes about three minutes, during which time no +copy of the database accepts changes. +

The opposite possibility is that a secondary site's clock +(14:50:00) is ahead of the coordinator's +(14:46:30). When the coordinator sends a guarantee message +good until 14:47:30), it has already expired according to the +secondary clock. Believing that it is out of contact with the +coordinator, the secondary site stops sending votes for the coordinator and +tries get itself elected as coordinator. This is appropriate if the +coordinator has actually failed, but is inappropriate when there is no actual +outage. +

The attempt of a single secondary site to get elected as the new +coordinator usually does not affect the performance of the other sites. +As long as their clocks agree with the coordinator's, they ignore the +other secondary site's request for votes and continue voting for the +current coordinator. However, if enough of the secondary sites's +clocks get ahead of the coordinator's, they can force election of a new +coordinator even though the current one is actually working fine. + + + + + + + + + +

A Flexible Coordinator Boosts Availability

Ubik uses timestamped messages to determine when coordinator +election is necessary, just as it does to keep the database copies +synchronized. As long as the coordinator receives vote messages from a +majority of the sites (it implicitly votes for itself), it is appropriate for +it to continue as coordinator because it is successfully distributing database +changes. A majority is defined as more than 50% of all database sites +when there are an odd number of sites; with an even number of sites, the +site with the lowest Internet address has an extra vote for breaking ties as +necessary.If the coordinator is not receiving sufficient votes, it +retires and the Ubik sites elect a new coordinator. This does not +happen spontaneously, but only when the coordinator really fails or stops +receiving a majority of the votes. The secondary sites have a built-in +bias to continue voting for an existing coordinator, which prevents undue +elections. +

The election of the new coordinator is by majority vote. The Ubik +subprocesses have a bias to vote for the site with the lowest Internet +address, which helps it gather the necessary majority quicker than if all the +sites were competing to receive votes themselves. During the election +(which normally lasts less than three minutes), clients can read information +from the database, but cannot make any changes. +

Ubik's election procedure makes it possible for each database server +process's coordinator to be on a different machine. For example, +if the Ubik coordinators for all four processes start out on machine A and the +Protection Server on machine A fails for some reason, then a different site +(say machine B) must be elected as the new Protection Database Ubik +coordinator. Machine B remains the coordinator for the Protection +Database even after the Protection Server on machine A is working +again. The failure of the Protection Server has no effect on the +Authentication, Backup, or VL Servers, so their coordinators remain on machine +A. +

Backing Up and Restoring the Administrative Databases

The AFS administrative databases store information that is +critical for AFS operation in your cell. If a database becomes +corrupted due to a hardware failure or other problem on a database server +machine, it likely to be difficult and time-consuming to recreate all of the +information from scratch. To protect yourself against loss of data, +back up the administrative databases to a permanent media, such as tape, on a +regular basis. The recommended method is to use a standard local disk +backup utility such as the UNIX tar command. +

When deciding how often to back up a database, consider the amount of data +that you are willing to recreate by hand if it becomes necessary to restore +the database from a backup copy. In most cells, the databases differ +quite a bit in how often and how much they change. Changes to the +Authentication Database are probably the least frequent, and consist mostly of +changed user passwords. Protection Database and VLDB changes are +probably more frequent, as users add or delete groups and change group +memberships, and as you and other administrators create or move +volumes. The number and frequency of changes is probably greatest in +the Backup Database, particularly if you perform backups every day. +

The ease with which you can recapture lost changes also differs for the +different databases: +

If regular users make a large proportion of the changes to the +Authentication Database and Protection Database in your cell, then recovering +them possibly requires a large amount of detective work and interviewing of +users, assuming that they can even remember what changes they made at what +time. +
Recovering lost changes to the VLDB is more straightforward, because you +can use the vos syncserv and vos syncvldb commands to +correct any discrepancies between the VLDB and the actual state of volumes on +server machines. Running these commands can be time-consuming, +however. +
The configuration information in the Backup Database (Tape Coordinator +port offsets, volume sets and entries, the dump hierarchy, and so on) probably +does not change that often, in which case it is not that hard to recover a few +recent changes. In contrast, there are likely to be a large number of +new dump records resulting from dump operations. You can recover these +records by using the -dbadd argument to the backup +scantape command, reading in information from the backup tapes +themselves. This can take a long time and require numerous tape +changes, however, depending on how much data you back up in your cell and how +you append dumps. Furthermore, the backup scantape command +is subject to several restrictions. The most basic is that it halts if +it finds that an existing dump record in the database has the same dump ID +number as a dump on the tape it is scanning. If you want to continue +with the scanning operation, you must locate and remove the existing record +from the database. For further discussion, see the backup +scantape command's reference page in the IBM AFS +Administration Reference. +

These differences between the databases possibly suggest backing up the +database at different frequencies, ranging from every few days or weekly for +the Backup Database to every few weeks for the Authentication Database. +On the other hand, it is probably simpler from a logistical standpoint to back +them all up at the same time (and frequently), particularly if tape +consumption is not a major concern. Also, it is not generally necessary +to keep backup copies of the databases for a long time, so you can recycle the +tapes fairly frequently. + + +

To back up the administrative databases

Log in as the local superuser root on a database server machine +that is not the synchronization site. The machine with the highest IP +address is normally the best choice, since it is least likely to become the +synchronization site in an election. +
Issue the bos shutdown command to shut down +the relevant server process on the local machine. For a complete +description of the command, see To stop processes temporarily. +
For the -instance argument, specify one or more database server +process names (buserver for the Backup Server, kaserver +for the Authentication Server, ptserver for the Protection Server, +or vlserver for the Volume Location Server. Include the +-localauth flag because you are logged in as the local superuser +root but do not necessarily have administrative tokens. +
```
   # bos shutdown <machine name> -instance <instances>⁺ -localauth [-wait]
+
```
+
Use a local disk backup utility, such as the UNIX tar command, +to transfer one or more database files to tape. If the local database +server machine does not have a tape device attached, use a remote copy command +to transfer the file to a machine with a tape device, then use the +tar command there. +
The following command sequence backs up the complete contents of the +/usr/afs/db directory +
```
   # cd /usr/afs/db
+   # tar cvf  tape_device  .
+
```
+
To back up individual database files, substitute their names for the period +in the preceding tar command: +
- bdb.DB0 for the Backup Database +
- kaserver.DB0 for the Authentication Database +
- prdb.DB0 for the Protection Database +
- vldb.DB0 for the VLDB +
+
Issue the bos start command to restart the server processes on +the local machine. For a complete description of the command, see To start processes by changing their status flags to Run. Provide the same values for the -instance +argument as in Step 2, and the -localauth flag for the same +reason. +
```
   # bos start <machine name> -instance <server process name>⁺ -localauth
+
```
+

+ + +

To restore an administrative database

Log in as the local superuser root on each database server +machine in the cell. +
Working on one of the machines, issue the bos +shutdown command once for each database server machine, to shut down the +relevant server process on all of them. For a complete description of +the command, see To stop processes temporarily. +
For the -instance argument, specify one or more database server +process names (buserver for the Backup Server, kaserver +for the Authentication Server, ptserver for the Protection Server, +or vlserver for the Volume Location Server. Include the +-localauth flag because you are logged in as the local superuser +root but do not necessarily have administrative tokens. +
```
   # bos shutdown <machine name> -instance <instances>⁺ -localauth [-wait]
+
```
+
Remove the database from each database server machine, by issuing the +following commands on each one. +
```
   # cd /usr/afs/db
+
```
+
For the Backup Database: +
```
   # rm bdb.DB0
+   # rm bdb.DBSYS1
+
```
+
For the Authentication Database: +
```
   # rm kaserver.DB0
+   # rm kaserver.DBSYS1
+
```
+
For the Protection Database: +
```
   # rm prdb.DB0
+   # rm prdb.DBSYS1
+
```
+
For the VLDB: +
```
   # rm vldb.DB0
+   # rm vldb.DBSYS1
+
```
+
Using the local disk backup utility that you used to back up the database, +copy the most recently backed-up version of it to the appropriate file on the +database server machine with the lowest IP address. The following is an +appropriate tar command if the synchronization site has a tape +device attached: +
```
   # cd /usr/afs/db
+   # tar xvf tape_device  database_file
+
```
+
where database_file is one of the following: +
- bdb.DB0 for the Backup Database +
- kaserver.DB0 for the Authentication Database +
- prdb.DB0 for the Protection Database +
- vldb.DB0 for the VLDB +
+
Working on one of the machines, issue the bos start command to +restart the server process on each of the database server machines in +turn. Start with the machine with the lowest IP address, which becomes +the synchronization site for the Backup Database. Wait for it to +establish itself as the synchronization site before repeating the command to +restart the process on the other database server machines. For a +complete description of the command, see To start processes by changing their status flags to Run. Provide the same values for the -instance +argument as in Step 2, and the -localauth flag for the same +reason. +
```
   # bos start <machine name> -instance  <server process name>⁺  -localauth
+
```
+
If the database has changed since you last backed it up, issue the +appropriate commands from the instructions in the indicated sections to +recreate the information in the restored database. If issuing +pts commands, you must first obtain administrative tokens. +The backup and vos commands accept the +-localauth flag if you are logged in as the local superuser +root, so you do not need administrative tokens. The +Authentication Server always performs a separate authentication anyway, so you +only need to include the -admin argument if issuing kas +commands. +
- To define or remove volume sets and volume entries in the Backup Database, +see Defining and Displaying Volume Sets and Volume Entries. +
- To edit the dump hierarchy in the Backup Database, see Defining and Displaying the Dump Hierarchy. +
- To define or remove Tape Coordinator port offset entries in the Backup +Database, see Configuring Tape Coordinator Machines and Tape Devices. +
- To restore dump records in the Backup Database, see To scan the contents of a tape. +
- To recreate Authentication Database entries or password changes for users, +see the appropriate section of Administering User Accounts. +
- To recreate Protection Database entries or group membership information, +see the appropriate section of Administering the Protection Database. +
- To synchronize the VLDB with volume headers, see Synchronizing the VLDB and Volume Headers. +
+

+ + + + + + +

Installing Server Process Software

This section explains how to install new server process +binaries on file server machines, how to revert to a previous version if the +current version is not working properly, and how to install new disks to house +AFS volumes on a file server machine. +

The most frequent reason to replace a server process's binaries is to +upgrade AFS to a new version. In general, installation instructions +accompany the updated software, but this chapter provides an additional +reference. +

Each AFS server machine must store the server process binaries in a local +disk directory, called /usr/afs/bin by convention. For +predictable system performance, it is best that all server machines run the +same build level, or at least the same version, of the server software. +For instructions on checking AFS build level, see Displaying A Binary File's Build Level. +

The Update Server makes it easy to distribute a consistent version of +software to all server machines. You designate one server machine of +each system type as the binary distribution machine by running the +server portion of the Update Server (upserver process) on +it. All other server machines of that system type run the client +portion of the Update Server (upclientbin process) to retrieve +updated software from the binary distribution machine. The IBM AFS +Quick Beginnings explains how to install the appropriate +processes. For more on binary distribution machines, see Binary Distribution Machines. +

When you use the Update Server, you install new binaries on binary +distribution machines only. If you install binaries directly on a +machine that is running the upclientbin process, they are +overwritten the next time the process compares the contents of the local +/usr/afs/bin directory to the contents on the system control +machine, by default within five minutes. +

The following instructions explain how to use the appropriate commands from +the bos suite to install and uninstall server binaries. + + + + + +

Installing New Binaries

An AFS server process does not automatically switch to a new +process binary file as soon as it is installed in the /usr/afs/bin +directory. The process continues to use the previous version of the +binary file until it (the process) next restarts. By default, the BOS +Server restarts processes for which there are new binary files every day at +5:00 a.m., as specified in the +/usr/afs/local/BosConfig file. To display or change this +binary restart time, use the bos getrestart and bos +setrestart commands, as described in Setting the BOS Server's Restart Times. +

You can force the server machine to start using new server process binaries +immediately by issuing the bos restart command as described in the +following instructions. +

You do not need to restart processes when you install new command suite +binaries. The new binary is invoked automatically the next time a +command from the suite is issued. + + + + + +

When you use the bos install command, the BOS Server +automatically saves the current version of a binary file by adding a +.BAK extension to its name. It renames the current +.BAK version, if any, to the .OLD version, +if there is no .OLD version already. If there is a +current .OLD version, the current .BAK +version must be at least seven days old to replace it. +

It is best to store AFS binaries in the /usr/afs/bin directory, +because that is the only directory the BOS Server automatically checks for new +binaries. You can, however, use the bos install +command's -dir argument to install non-AFS binaries into other +directories on a server machine's local disk. See the +command's reference page in the IBM AFS Administration +Reference for further information. + + +

To install new server binaries

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Verify that the binaries are available in the source directory from which +you are installing them. If the machine is also an AFS client, you can +retrieve the binaries from a central directory in AFS. Otherwise, you +can obtain them directly from the AFS distribution media, from a local disk +directory where you previously installed them, or from a remote machine using +a transfer utility such as the ftp command. +
Issue the bos install command for the binary +distribution machine. (If you have forgotten which machine is +performing that role, see To locate the binary distribution machine for a system type.) +
```
   % bos install <machine name> <files to install>⁺
+
```
+
where +
+
i +
Is the shortest acceptable abbreviation of install. +
machine name +
Names the binary distribution machine. +
files to install +
Names each binary file to install into the local /usr/afs/bin +directory. Partial pathnames are interpreted relative to the current +working directory. The last element in each pathname (the filename +itself) matches the name of the file it is replacing, such as +bosserver or volserver for server processes, +bos or vos for commands. +
Each AFS server process other than the fs process uses a single +binary file. The fs process uses three binary files: +fileserver, volserver, and salvager. +Installing a new version of one component does not necessarily mean that you +need to replace all three. +
+
Repeat Step 3 for each binary distribution machine. +
(Optional) If you want to restart processes to use the new +binaries immediately, wait until the upclientbin process retrieves +them from the binary distribution machine. You can verify the +timestamps on binary files by using the bos getdate command as +described in Displaying Binary Version Dates. When the binary files are available on each server +machine, issue the bos restart command, for which complete +instructions appear in Stopping and Immediately Restarting Processes. +
If you are working on an AFS client machine, it is a wise precaution to +have a copy of the bos command suite binaries on the local disk +before restarting server processes. In the conventional configuration, +the /usr/afsws/bin directory that houses the bos command +binary on client machines is a symbolic link into AFS, which conserves local +disk space. However, restarting certain processes (particularly the +database server processes) can make the AFS filespace inaccessible, +particularly if a problem arises during the restart. Having a local +copy of the bos binary enables you to uninstall or reinstall +process binaries or restart processes even in this case. Use the +cp command to copy the bos command binary from the +/usr/afsws/bin directory to a local directory such as +/tmp. +
Restarting a process causes a service outage. It is best to perform +the restart at times of low system usage if possible. +
```
   % bos restart <machine name> <instances>⁺
+
```
+

+ + + + + + + + +

Reverting to the Previous Version of Binaries

In rare cases, installing a new binary can cause problems +serious enough to require reverting to the previous version. Just as +with installing binaries, consistent system performance requires reverting +every server machine back to the same version. Issue the bos +uninstall command described here on each binary distribution +machine. +

When you use the bos uninstall command, the BOS Server discards +the current version of a binary file and promotes the .BAK +version of the file by removing the extension. It renames the current +.OLD version, if any, to .BAK. +

If there is no current .BAK version, the bos +uninstall command operation fails and generates an error message. +If a .OLD version still exists, issue the mv +command to rename it to .BAK before reissuing the bos +uninstall command. +

Just as when you install new binaries, the server processes do not start +using a reverted version immediately. Presumably you are reverting +because the current binaries do not work, so the following instructions have +you restart the relevant processes. + + +

To revert to the previous version of binaries

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Verify that the .BAK version of each relevant binary is +available in the /usr/afs/bin directory on each binary distribution +machine. If necessary, you can use the bos getdate command +as described in Displaying Binary Version Dates. If necessary, rename the .OLD +version to .BAK +
Issue the bos uninstall command for a binary +distribution machine. (If you have forgotten which machine is +performing that role, see To locate the binary distribution machine for a system type.) +
```
   % bos uninstall <machine name> <files to uninstall>⁺
+
```
+
where +
+
u +
Is the shortest acceptable abbreviation of uninstall. +
machine name +
Names the binary distribution machine. +
files to uninstall +
Names each binary file in the /usr/afs/bin directory to replace +with its .BAK version. The file name alone is +sufficient, because the /usr/afs/bin directory is assumed. +
+
Repeat Step 3 for each binary distribution machine. +
Wait until the upclientbin process on each server machine +retrieves the reverted from the binary distribution machine. You can +verify the timestamps on binary files by using the bos getdate +command as described in Displaying Binary Version Dates. When the binary files are available on each server +machine, issue the bos restart command, for which complete +instructions appear in Stopping and Immediately Restarting Processes. +
If you are working on an AFS client machine, it is a wise precaution to +have a copy of the bos command suite binaries on the local disk +before restarting server processes. In the conventional configuration, +the /usr/afsws/bin directory that houses the bos command +binary on client machines is a symbolic link into AFS, which conserves local +disk space. However, restarting certain processes (particularly the +database server processes) can make the AFS filespace inaccessible, +particularly if a problem arises during the restart. Having a local +copy of the bos binary enables you to uninstall or reinstall +process binaries or restart processes even in this case. Use the +cp command to copy the bos command binary from the +/usr/afsws/bin directory to a local directory such as +/tmp. +
```
   % bos restart <machine name> <instances>⁺
+
```
+

+ + + + + + +

Displaying Binary Version Dates

You can check the compilation dates for all three versions +of a binary file in the /usr/afs/bin directory--the current, +.BAK and .OLD versions. This is +useful for verifying that new binaries have been copied to a file server +machine from its binary distribution machine before restarting a server +process to use the new binaries. +

To check dates on binaries in a directory other than +/usr/afs/bin, add the -dir argument. See the IBM +AFS Administration Reference. + + +

To display binary version dates

Issue the bos getdate command. +
```
   % bos getdate <machine name> <files to check>⁺
+
```
+
where +
+
getd +
Is the shortest acceptable abbreviation of getdate. +
machine name +
Name the file server machine for which to display binary dates. +
files to check +
Names each binary file to display. +
+

+ + + + + + + + +

Removing Obsolete Binary Files

When processes with new binaries have been running without +problems for a number of days, it is generally safe to remove the +.BAK and .OLD versions from the +/usr/afs/bin directory, both to reduce clutter and to free space on +the file server machine's local disk. +

You can use the bos prune command's flags to remove the +following types of files: +

To remove files in the /usr/afs/bin directory with a +.BAK extension, use the -bak flag. +
To remove files in the /usr/afs/bin directory with a +.OLD extension, use the -old flag. +
To remove files in the /usr/afs/logs directory called +core, with any extension, use the -core flag. +
To remove all three types of files, use the -all flag. +

+ + +

To remove obsolete binaries

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos prune command with one or more of its +flags. +
```
   % bos prune <machine name> [-bak] [-old] [-core] [-all]
+
```
+
where +
+
p +
Is the shortest acceptable abbreviation of prune. +
machine name +
Names the file server machine on which to remove obsolete files. +
-bak +
Removes all the files with a .BAK extension from the +/usr/afs/bin directory. Do not combine this flag with the +-all flag. +
-old +
Removes all the files a .OLD extension from the +/usr/afs/bin directory. Do not combine this flag with the +-all flag. +
-core +
Removes all core files from the /usr/afs/logs directory. +Do not combine this flag with the -all flag +
-all +
Combines the effect of the other three flags. Do not combine it +with the other three flags. +
+

Displaying A Binary File's Build Level

For the most consistent performance on a server machine, and +cell-wide, it is best for all server processes to come from the same AFS +distribution. Every AFS binary includes an ASCII string that specifies +its version, or build level. To display it, use the +strings and grep commands, which are included in most +UNIX distributions. + + + + +

To display an AFS binary's build level

Change to the directory that houses the binary file . If you are +not sure where the binary resides, issue the which command. +
```
   % which binary_file
+   /bin_dir_path/binary_file
+   % cd bin_dir_path
+
```
+
Issue the strings command to extract all ASCII strings from the +binary file. Pipe the output to the grep command to locate +the relevant line. +
```
   % strings ./binary_file | grep Base
+
```
+
The output reports the AFS build level in a format like the +following: +
```
   @(#)Base configuration afsversion  build_level
+
```
+
For example, the following string indicates the binary is from AFS +3.6 build 3.0: +
```
   @(#)Base configuration afs3.6 3.0
+
```
+

+ + + + + +

Maintaining the Server CellServDB File

Every file server machine maintains a list of its home +cell's database server machines in the local disk file +/usr/afs/etc/CellServDB on its local disk. Both database +server processes and non-database server processes consult the file: +

The database server processes (the Authentication, Backup, Protection, and +Volume Location Servers) maintain constant contact with their peers in order +to keep their copies of the replicated administrative databases +synchronized. +
As detailed in Replicating the AFS Administrative Databases, the database server processes use the Ubik utility to +synchronize the information in the databases they maintain. The Ubik +coordinator at the synchronization site for each database maintains the single +read/write copy of the database and distributes changes to the secondary sites +as necessary. It must maintain contact with a majority of the secondary +sites to remain the coordinator, and consults the CellServDB file +to learn how many peers it has and on which machines they are running. +
If the coordinator loses contact with the majority of its peers, they all +cooperate to elect a new coordinator by majority vote. During the +election, all of the Ubik processes consult the CellServDB file to +learn where to send their votes, and what number constitutes a +majority. +
The non-database server processes must know which machines are running the +database server processes in order to retrieve information from the +databases. For example, the first time that a user accesses an AFS +file, the File Server that houses it contacts the Protection Server to obtain +a list of the user's group memberships (the list is called a current +protection subgroup, or CPS). The File Server uses the CPS as it +determines if the access control list (ACL) protecting the file grants the +required permissions to the user (for more details, see About the Protection Database). +

+ +

The consequences of missing or incorrect information in the +CellServDB file are as follows: +

If the file does not list a machine, then it is effectively not a database +server machine even if the database server processes are running. The +Ubik coordinator does not send it database updates or include it in the count +that establishes a majority. It does not participate in Ubik elections, +and so refuses to distribute database information to any client machines that +happen to contact it (which they can do if their +/usr/vice/etc/CellServDB file lists it). Users of the client +machine must wait for a timeout before they can contact a correctly +functioning database server machine. +
If the file lists a machine that is not running the database server +processes, the consequences can be serious. The Ubik coordinator cannot +send it database updates, but includes it in the count that establishes a +majority. If valid secondary sites go down and stop sending their votes +to the coordinator, it can wrongly appear that the coordinator no longer has +the majority it needs. The resulting election of a new coordinator +causes a service outage during which information from the database becomes +unavailable. Furthermore, the lack of a vote from the incorrectly +listed site can disturb the election, if it makes the other sites believe that +a majority of sites are not voting for the new coordinator. +
A more minor consequence is that non-database server processes attempt to +contact the database server processes on the machine. They experience a +timeout delay because the processes are not running. +

Note that the /usr/afs/etc/CellServDB file on a server machine +is not the same as the /usr/vice/etc/CellServDB file on client +machine. The client version includes entries for foreign cells as well +as the local cell. However, it is important to update both versions of +the file whenever you change your cell's database server machines. +A server machine that is also a client needs to have both files, and you need +to update them both. For more information on maintaining the client +version of the CellServDB file, see Maintaining Knowledge of Database Server Machines. + + + +

Distributing the Server CellServDB File

To avoid the negative consequences of incorrect information +in the /usr/afs/etc/CellServDB file, you must update it on all of +your cell's server machines every time you add or remove a database +server machine. The IBM AFS Quick Beginnings provides +complete instructions for installing or removing a database server machine and +for updating the CellServDB file in that context. This +section explains how to distribute the file to your server machines and how to +make other cells aware of the changes if you participate in the AFS global +name space. +

If you use the United States edition of AFS, use the Update Server to +distribute the central copy of the server CellServDB file stored on +the cell's system control machine. If you use the international +edition of AFS, instead change the file on each server machine +individually. For further discussion of the system control machine and +why international cells must not use it for files in the +/usr/afs/etc directory, see The System Control Machine. For instructions on configuring +the Update Server when using the United States version of AFS, see the +IBM AFS Quick Beginnings. +

To avoid formatting errors that can cause errors, always use the bos +addhost and bos removehost commands, rather than editing the +file directly. You must also restart the database server processes +running on the machine, to initiate a coordinator election among the new set +of database server machines. This step is included in the instructions +that appear in To add a database server machine to the CellServDB file and To remove a database server machine from the CellServDB file. For instructions on displaying the +contents of the file, see To display a cell's database server machines. +

If you make your cell accessible to foreign users as part of the AFS global +name space, you also need to inform other cells when you change your +cell's database server machines. The AFS Support group maintains a +CellServDB file that lists all cells that participate in the AFS +global name space, and can change your cell's entry at your +request. For further details, see Making Your Cell Visible to Others. +

Another way to advertise your cell's database server machines is to +maintain a copy of the file at the conventional location in your AFS +filespace, +/afs/cell_name/service/etc/CellServDB.local. +For further discussion, see The Third Level. + + + + + + +

To display a cell's database server machines

Issue the bos listhosts command. If you have maintained +the file properly, the output is the same on every server machine, but the +machine name argument enables you to check various machines if you +wish. +
```
   % bos listhosts <machine name> [<cell name>]
+
```
+
where +
+
listh +
Is the shortest acceptable abbreviation of listhosts. +
machine name +
Specifies the server machine from which to display the +/usr/afs/etc/CellServDB file. +
cell name +
Specifies the complete Internet domain name of a foreign cell. You +must already know the name of at least one server machine in the cell, to +provide as the machine name argument. +
+

The output lists the machines in the order they appear in the +CellServDB file on the specified server machine. It assigns +each one a Host index number, as in the following example. +There is no implied relationship between the index and a machine's IP +address, name, or role as Ubik coordinator or secondary site. +

   % bos listhosts fs1.abc.com
+   Cell name is abc.com
+       Host 1 is fs1.abc.com
+       Host 2 is fs7.abc.com
+       Host 3 is fs4.abc.com
+

The output lists machines by name rather than IP address as long as the +naming service (such as the Domain Name Service or local host table) is +functioning properly. To display IP addresses, login to a server +machine as the local superuser root and use a text editor or +display command, such as the cat command, to view the +/usr/afs/etc/CellServDB file. + + + + + + + + + + + + +

To add a database server machine to the CellServDB file

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos addhost command to add each new database server +machine to the CellServDB file. If you use the United States +edition of AFS, specify the system control machine as machine +name. (If you have forgotten which machine is the system control +machine, see The Output on the System Control Machine.) If you use the international edition of AFS, repeat +the command on each or your cell's server machines in turn by +substituting its name for machine name. +
```
   % bos addhost  <machine name>  <host name>⁺
+
```
+
where +
+
addh +
Is the shortest acceptable abbreviation of addhost. +
machine name +
Names the system control machine, if you are using the United States +edition of AFS. If you are using the international edition of AFS, it +names each of your server machines in turn. +
host name +
Specifies the fully qualified hostname of each database server machine to +add to the CellServDB file (for example: +fs4.abc.com). The BOS Server uses the +gethostbyname( ) routine to obtain each machine's IP +address and records both the name and address automatically. +
+
Restart the Authentication Server, Backup Server, Protection Server, and +VL Server on every database server machine, so that the new set of machines +participate in the election of a new Ubik coordinator. The instruction +uses the conventional names for the processes; make the appropriate +substitution if you use different process names. For complete syntax, +see Stopping and Immediately Restarting Processes. +
Important: Repeat the following command in quick +succession on all of the database server machines. +
```
   % bos restart <machine name> buserver kaserver ptserver vlserver
+
```
+
Edit the /usr/vice/etc/CellServDB file on each of your +cell's client machines. For instructions, see Maintaining Knowledge of Database Server Machines. +
If you participate in the AFS global name space, please have one of your +cell's designated site contacts register the changes you have made with +the AFS Product Support group. +
If you maintain a central copy of your cell's server +CellServDB file in the conventional location +(/afs/cell_name/service/etc/CellServDB.local), +edit the file to reflect the change. +

+ + + + + + + + + + + +

To remove a database server machine from the CellServDB file

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos removehost command to remove each database server +machine from the CellServDB file. If you use the United +States edition of AFS, specify the system control machine as machine +name. (If you have forgotten which machine is the system control +machine, see The Output on the System Control Machine.) If you use the international edition of AFS, repeat +the command on each or your cell's server machines in turn by +substituting its name for machine name. +
```
   % bos removehost <machine name>  <host name>⁺
+
```
+
where +
+
removeh +
Is the shortest acceptable abbreviation of removehost. +
machine name +
Names the system control machine, if you are using the United States +edition of AFS. If you are using the international edition of AFS, it +names each of your server machines in turn. +
host name +
Specifies the fully qualified hostname of each database server machine to +remove from the CellServDB file (for example: +fs4.abc.com). +
+
Restart the Authentication Server, Backup Server, Protection Server, and +VL Server on every database server machine, so that the new set of machines +participate in the election of a new Ubik coordinator. The instruction +uses the conventional names for the processes; make the appropriate +substitution if you use different process names. For complete syntax, +see Stopping and Immediately Restarting Processes. +
Important: Repeat the following command in quick +succession on all of the database server machines. +
```
   % bos restart <machine name> buserver kaserver ptserver vlserver
+
```
+
Edit the /usr/vice/etc/CellServDB file on each of your +cell's client machines. For instructions, see Maintaining Knowledge of Database Server Machines. +
If you participate in the AFS global name space, please have one of your +cell's designated site contacts register the changes you have made with +the AFS Product Support group. +
If you maintain a central copy of your cell's server +CellServDB file in the conventional location +(/afs/cell_name/service/etc/CellServDB.local), +edit the file to reflect the change. +

Managing Authentication and Authorization Requirements

This section describes how the AFS server processes +guarantee that only properly authorized users perform privileged commands, by +checking authorization checking and mutually authenticating with their +clients. It explains how you can control authorization checking +requirements on a per-machine or per-cell basis, and how to bypass mutual +authentication when issuing commands. + + + + + + +

Authentication versus Authorization

Many AFS commands are privileged in that the AFS +server process invoked by the command performs it only for a properly +authorized user. The server process performs the following two tests to +determine if someone is properly authorized: +

In the authentication test, the server process mutually +authenticates with the command interpreter, Cache Manager, or other client +process that is acting on behalf of a user or application. The goal of +this test is to determine who is issuing the command. The server +process verifies that the issuer really is who he or she claims to be, by +examining the server ticket and other components of the issuer's +token. (Secondarily, it allows the client process to verify that the +server process is genuine.) If the issuer has no token or otherwise +fails the test, the server process assigns him or her the identity +anonymous, a completely unprivileged user. For a more +complete description of mutual authentication, see A More Detailed Look at Mutual Authentication. +
Many individual commands enable you to bypass the authentication test by +assuming the anonymous identity without even attempting to mutually +authenticate. Note, however, that this is futile if the command is +privileged and the server process is still performing the authorization test, +because in that case the process refuses to execute privileged commands for +the anonymous user. +

In the authorization test, the server process determines if the +issuer is authorized to use the command by consulting a list of privileged +users. The goal of this test is to determine what the issuer is allowed +to do. Different server processes consult different lists of users, as +described in Managing Administrative Privilege. The server process refuses to execute any privileged +command for an unauthorized issuer. If a command has no privilege +requirements, the server process skips this step and executes and +immediately. +

Note:

Never place the anonymous user or the +system:anyuser group on a privilege list; it makes +authorization checking meaningless. +

You can use the bos setauth command to control whether the +server processes on a server machine check for authorization. Other +server machines are not affected. Keep in mind that turning off +authorization checking is a grave security risk, because the server processes +on that machine perform any action for any user. +

+ + + + +

Controlling Authorization Checking on a Server Machine

Disabling authorization checking is a serious breach of +security because it means that the AFS server processes on a file server +machine performs any action for any user, even the anonymous +user. +

The only time it is common to disable authorization checking is when +installing a new file server machine (see the IBM AFS Quick +Beginnings). It is necessary then because it is not possible to +configure all of the necessary security mechanisms before performing other +actions that normally make use of them. For greatest security, work at +the console of the machine you are installing and enable authorization +checking as soon as possible. +

During normal operation, the only reason to disable authorization checking +is if an error occurs with the server encryption keys, leaving the servers +unable to authenticate users properly. For instructions on handling +key-related emergencies, see Handling Server Encryption Key Emergencies. +

You control authorization checking on each file server machine +separately; turning it on or off on one machine does not affect the +others. Because client machines generally choose a server process at +random, it is hard to predict what authorization checking conditions prevail +for a given command unless you make the requirement the same on all +machines. To turn authorization checking on or off for the entire cell, +you must repeat the appropriate command on every file server machine. +

The server processes constantly monitor the directory +/usr/afs/local on their local disks to determine if they need to +check for authorization. If the file called NoAuth appears +in that directory, then the servers do not check for authorization. +When it is not present (the usual case), they perform authorization +checking. +

Control the presence of the NoAuth file through the BOS +Server. When you disable authorization checking with the bos +setauth command (or, during installation, by putting the +-noauth flag on the command that starts up the BOS Server), the BOS +Server creates the zero-length NoAuth file. When you +reenable authorization checking, the BOS Server removes the file. + + + + + +

To disable authorization checking on a server machine

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos setauth command to disable authorization +checking. +
```
   % bos setauth <machine name> off
+
```
+
where +
+
seta +
Is the shortest acceptable abbreviation of setauth. +
machine name +
Specifies the file server machine on which server processes do not check +for authorization. +
+

+ + + +

To enable authorization checking on a server machine

Reenable authorization checking. (No privilege is required because +the machine is not currently checking for authorization.) For detailed +syntax information, see the preceding section. +
```
   % bos setauth <machine name> on
+
```
+

+ + +

Bypassing Mutual Authentication for an Individual Command

Several of the server processes allow any user (not just +system administrators) to disable mutual authentication when issuing a +command. The server process treats the issuer as the unauthenticated +user anonymous. +

The facilities for preventing mutual authentication are provided for use in +emergencies (such as the key emergency discussed in Handling Server Encryption Key Emergencies). During normal circumstances, authorization checking +is turned on, making it useless to prevent authentication: the server +processes refuse to perform privileged commands for the user +anonymous. +

It can be useful to prevent authentication when authorization checking is +turned off. The very act of trying to authenticate can cause problems +if the server cannot understand a particular encryption key, as is likely to +happen in a key emergency. + + + + + + + + +

To bypass mutual authentication for bos, kas, pts, and vos commands

Provide the -noauth flag which is available on +many of the commands in the suites. To verify that a command accepts +the flag, issue the help command in its suite, or consult the +command's reference page in the IBM AFS Administration +Reference (the reference page also specifies the shortest acceptable +abbreviation for the flag on each command). The suites' +apropos and help commands do not themselves accept the +flag. +

You can bypass mutual authentication for all kas commands issued +during an interactive session by including the -noauth flag on the +kas interactive command. If you have already entered +interactive mode with an authenticated identity, issue the (kas) +noauthentication command to assume the anonymous +identity. + +

To bypass mutual authentication for fs commands

This is not possible, except by issuing the unlog command to +discard your tokens before issuing the fs command. +

Adding or Removing Disks and Partitions

AFS makes it very easy to add storage space to your cell, +just by adding disks to existing file server machines. This section +explains how to install or remove a disk used to store AFS volumes. +(Another way to add storage space is to install additional server machines, as +instructed in the IBM AFS Quick Beginnings.) +

Both adding and removing a disk cause at least a brief file system outage, +because you must restart the fs process to have it recognize the +new set of server partitions. Some operating systems require that you +shut the machine off before adding or removing a disk, in which case you must +shut down all of the AFS server processes first. Otherwise, the +AFS-related aspects of adding or removing a disk are not complicated, so the +duration of the outage depends mostly on how long it takes to install or +remove the disk itself. +

The following instructions for installing a new disk completely prepare it +to house AFS volumes. You can then use the vos create +command to create new volumes, or the vos move command to move +existing ones from other partitions. For instructions, see Creating Read/write Volumes and Moving Volumes. The instructions for removing a +disk are basically the reverse of the installation instructions, but include +extra steps that protect against data loss. +

A server machines can house 256 AFS server partitions, each one mounted at +a directory with a name of the form /vicepindex, where +index is one or two lowercase letters. By convention, the +first partition on a machine is mounted at /vicepa, the second at +/vicepb, and so on to the twenty-sixth at +/vicepz. Additional partitions are mounted at +/vicepaa through /vicepaz and so on up to +/vicepiv. Using the letters consecutively is not required, +but is simpler. +

Mount each /vicep directory directly under the local file +system's root directory ( / ), not as a subdirectory of any +other directory; for example, /usr/vicepa is not an acceptable +location. You must also map the directory to the partition's +device name in the file server machine's file systems registry file +(/etc/fstab or equivalent). +

These instructions assume that the machine's AFS initialization file +includes the following command to restart the BOS Server after each +reboot. The BOS Server starts the other AFS server processes listed in +the local /usr/afs/local/BosConfig file. For information on +the bosserver command's optional arguments, see its reference +page in the IBM AFS Administration Reference. +

   /usr/afs/bin/bosserver &
+

+ + + + + + + +

To add and mount a new disk to house AFS volumes

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Decide how many AFS partitions to divide the new disk into and the names +of the directories at which to mount them (the introduction to this section +describes the naming conventions). To display the names of the existing +server partitions on the machine, issue the vos listpart +command. Include the -localauth flag because you are logged +in as the local superuser root but do not necessarily have +administrative tokens. +
```
   # vos listpart <machine name> -localauth
+
```
+
where +
+
listp +
Is the shortest acceptable abbreviation of listpart. +
machine name +
Names the local file server machine. +
-localauth +
Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents it to the BOS Server during mutual authentication. +
+
Create each directory at which to mount a partition. +
```
   # mkdir /vicepx[x]
+
```
+ + + + +
Using a text editor, create an entry in the machine's file +systems registry file (/etc/fstab or equivalent) for each new disk +partition, mapping its device name to the directory you created in the +previous step. Refer to existing entries in the file to learn the +proper format, which varies for different operating systems. +
If the operating system requires that you shut off the machine +to install a new disk, issue the bos shutdown command to shut down +all AFS server processes other than the BOS Server (it terminates safely when +you shut off the machine). Include the -localauth flag +because you are logged in as the local superuser root but do not +necessarily have administrative tokens. For a complete description of +the command, see To stop processes temporarily. +
```
   # bos shutdown <machine name> -localauth [-wait]
+
```
+
If necessary, shut off the machine. Install and format +the new disk according to the instructions provided by the disk and operating +system vendors. If necessary, edit the disk's partition table to +reflect the changes you made to the files system registry file in step 4; consult the operating system documentation for +instructions. +
If you shut off the machine down in step 6, turn it on. Otherwise, issue the bos +restart command to restart the fs process, forcing it to +recognize the new set of server partitions. Include the +-localauth flag because you are logged in as the local superuser +root but do not necessarily have administrative tokens. For +complete instructions for the bos restart command, see Stopping and Immediately Restarting Processes. +
```
   # bos restart <machine name>  fs -localauth 
+
```
+
Issue the bos status command to verify that all server +processes are running correctly. For more detailed instructions, see Displaying Process Status and Information from the BosConfig File. +
```
   # bos status <machine name>
+
```
+

+ + + + + +

To unmount and remove a disk housing AFS volumes

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the vos listvol command to list the volumes housed on +each partition of each disk you are about to remove, in preparation for +removing them or moving them to other partitions. For detailed +instructions, see Displaying Volume Headers. +
```
   % vos listvol <machine name> [<partition name>] 
+
```
+
Move any volume you wish to retain in the file system to another +partition. You can move only read/write volumes. For more +detailed instructions, and for instructions on moving read-only and backup +volumes, see Moving Volumes. +
```
   % vos move  <volume name or ID>  \
+        <machine name on source> <partition name on source>  \
+        <machine name on destination> <partition name on destination>
+
```
+
(Optional) If there are any volumes you do not wish to retain, +back them up using the vos dump command or the AFS Backup +System. See Dumping and Restoring Volumes or Backing Up Data, respectively. +
Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+ + +
Issue the umount command, repeating it for each partition on +the disk to be removed. +
```
   # cd /
+   # umount /dev/<partition_block_device_name>
+
```
+ +
Using a text editor, remove or comment out each +partition's entry from the machine's file systems registry file +(/etc/fstab or equivalent). +
Remove the /vicep directory associated with each +partition. +
```
   # rmdir /vicepxx
+
```
+
If the operating system requires that you shut off the machine to remove a +disk, issue the bos shutdown command to shut down all AFS server +processes other than the BOS Server (it terminates safely when you shut off +the machine). Include the -localauth flag because you are +logged in as the local superuser root but do not necessarily have +administrative tokens. For a complete description of the command, see To stop processes temporarily. +
```
   # bos shutdown <machine name> -localauth [-wait]
+
```
+
If necessary, shut off the machine. Remove the disk +according to the instructions provided by the disk and operating system +vendors. If necessary, edit the disk's partition table to reflect +the changes you made to the files system registry file in step 7; consult the operating system documentation for +instructions. +
If you shut off the machine down in step 10, turn it on. Otherwise, issue the bos +restart command to restart the fs process, forcing it to +recognize the new set of server partitions. Include the +-localauth flag because you are logged in as the local superuser +root but do not necessarily have administrative tokens. For +complete instructions for the bos restart command, see Stopping and Immediately Restarting Processes. +
```
   # bos restart <machine name>  fs -localauth 
+
```
+
Issue the bos status command to verify that all server +processes are running correctly. For more detailed instructions, see Displaying Process Status and Information from the BosConfig File. +
```
   # bos status <machine name>
+
```
+

+ + + + + + + + + + + +

Managing Server IP Addresses and VLDB Server Entries

The AFS support for multihomed file server machines is +largely automatic. The File Server process records the IP addresses of +its file server machine's network interfaces in the local +/usr/afs/local/sysid file and also registers them in a server +entry in the Volume Location Database (VLDB). The +sysid file and server entry are identified by the same unique +number, which creates an association between them. +

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. +

If you wish, you can control which interfaces the File Server registers in +its VLDB server entry by creating two files in the local +/usr/afs/local directory: NetInfo and +NetRestrict. Each time the File Server restarts, it builds a +list of the local machine's interfaces by reading the NetInfo +file, if it exists. If you do not create the file, 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 +NetRestrict file, if it exists. The File Server records the +resulting list in the sysid file and registers the interfaces in +the VLDB server entry that has the same unique identifier. +

On database server machines, the NetInfo and +NetRestrict files also determine which interfaces the Ubik database +synchronization library uses when communicating with the database server +processes running on other database server machines. +

There is a maximum number of IP addresses in each server entry, as +documented in the IBM AFS Release Notes. If a multihomed +file server machine has more interfaces than the maximum, AFS simply ignores +the excess ones. It is probably appropriate for such machines to use +the NetInfo and NetRestrict files to control which +interfaces are registered. +

If for some reason the sysid file no longer exists, the File +Server creates a new one with a new unique identifier. When the File +Server registers the contents of the new file, the Volume Location (VL) Server +normally recognizes automatically that the new file corresponds to an existing +server entry, and overwrites the existing server entry with the new file +contents and identifier. However, it is best not to remove the +sysid file if that can be avoided. +

Similarly, it is important not to copy the sysid file from one +file server machine to another. If you commonly copy the contents of +the /usr/afs directory from an existing machine as part of +installing a new file server machine, be sure to remove the sysid +file from the /usr/afs/local directory on the new machine before +starting the File Server. +

There are certain cases where the VL Server cannot determine whether it is +appropriate to overwrite an existing server entry with a new sysid +file's contents and identifier. It then refuses to allow the File +Server to register the interfaces, which prevents the File Server from +starting. This can happen if, for example, a new sysid file +includes two interfaces that currently are registered by themselves in +separate server entries. In such cases, error messages in the +/usr/afs/log/VLLog file on the VL Server machine and in the +/usr/afs/log/FileLog file on the file server machine indicate that +you need to use the vos changeaddr command to resolve the +problem. Contact the AFS Product Support group for instructions and +assistance. +

Except in this type of rare error case, the only appropriate use of the +vos changeaddr command is to remove a VLDB server entry completely +when you remove a file server machine from service. The VLDB can +accommodate a maximum number of server entries, as specified in the IBM +AFS Release Notes. Removing obsolete entries makes it possible to +allocate server entries for new file server machines as required. See +the instructions that follow. +

Do not use the vos changeaddr command to change the list of +interfaces registered in a VLDB server entry. To change a file server +machine's IP addresses and server entry, see the instructions that +follow. + + + +

To create or edit the server NetInfo file

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Using a text editor, open the /usr/afs/local/NetInfo +file. Place one IP address in dotted decimal format (for example, +192.12.107.33) on each line. The order +of entries is not significant. +
If you want the File Server to start using the revised list immediately, +use the bos restart command to restart the fs +process. For instructions, see Stopping and Immediately Restarting Processes. +

+ + + +

To create or edit the server NetRestrict file

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Using a text editor, open the /usr/afs/local/NetRestrict +file. Place one IP address in dotted decimal format on each +line. The order of the addresses is not significant. Use the +value 255 as a wildcard that represents all possible addresses in +that field. For example, the entry +192.12.105.255 indicates that the Cache +Manager does not register any of the addresses in the 192.12.105 +subnet. +
If you want the File Server to start using the revised list immediately, +use the bos restart command to restart the fs +process. For instructions, see Stopping and Immediately Restarting Processes. +

+ + +

To display all server entries from the VLDB

Issue the vos listaddrs command to display all server entries +from the VLDB. +
```
   % vos listaddrs
+
```
+
where lista is the shortest acceptable abbreviation of +listaddrs. +
The output displays all server entries from the VLDB, each on its own +line. If a file server machine is multihomed, all of its registered +addresses appear on the line. The first one is the one reported as a +volume's site in the output from the vos examine and vos +listvldb commands. +
VLDB server entries record IP addresses, and the command interpreter has +the local name service (either a process like the Domain Name Service or a +local host table) translate them to hostnames before displaying them. +If an IP address appears in the output, it is not possible to translate +it. +
The existence of an entry does not necessarily indicate that the machine +that is still an active file server machine. To remove obsolete server +entries, see the following instructions. +

+ + +

To remove obsolete server entries from the VLDB

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the vos changeaddr command to remove a server entry from +the VLDB. +
```
   % vos changeaddr <original IP address> -remove
+
```
+
where +
+
ch +
Is the shortest acceptable abbreviation of changeaddr. +
original IP address +
Specifies one of the IP addresses currently registered for the file server +machine in the VLDB. Any of a multihomed file server machine's +addresses are acceptable to identify it. +
-remove +
Removes the server entry. +
+

To change a server machine's IP addresses

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If the machine is the system control machine or a binary distribution +machine, and you are also changing its hostname, redefine all relevant +upclient processes on other server machines to refer to the new +hostname. Use the bos delete and bos create +commands as instructed in Creating and Removing Processes. +
If the machine is a database server machine, edit its entry in the +/usr/afs/etc/CellServDB file on every server machine in the cell to +list one of the new IP addresses. If you use the United States edition +of AFS, you can edit the file on the system control machine and wait the +required time (by default, five minutes) for the Update Server to distribute +the changed file to all server machines. +
If the machine is a database server machine, issue the bos +shutdown command to stop all server processes. If the machine is +also a file server, the volumes on it are inaccessible during this +time. For a complete description of the command, see To stop processes temporarily. +
```
   % bos shutdown <machine name>
+
```
+
Use the utilities provided with the operating system to change one or more +of the machine's IP addresses. +
If appropriate, edit the /usr/afs/local/NetInfo file, the +/usr/afs/local/NetRestrict file, or both, to reflect the changed +addresses. Instructions appear earlier in this section. +
If the machine is a database server machine, issue the bos +restart command to restart all server processes on the machine. +For complete instructions for the bos restart command, see Stopping and Immediately Restarting Processes. +
```
   % bos restart <machine name> -all
+
```
+
At the same time, issue the bos restart command on all other +database server machines in the cell to restart the database server processes +only (the Authentication, Backup, Protection, and Volume Location +Servers). Issue the commands in quick succession so that all of the +database server processes vote in the quorum election. +
```
   % bos restart <machine name> kaserver buserver ptserver vlserver
+
```
+
If you are changing IP addresses on every database server machine in the +cell, you must also issue the bos restart command on every file +server machine in the cell to restart the fs process. +
If the machine is not a database server machine, issue the bos +restart command to restart the fs process (if the machine is +a database server, you already restarted the process in the previous +step). The File Server automatically compiles a new list of interfaces, +records them in the /usr/afs/local/sysid file, and registers them +in its VLDB server entry. +
```
   % bos restart <machine name> fs
+
```
+
If the machine is a database server machine, edit its entry in the +/usr/vice/etc/CellServDB file on every client machine in the cell +to list one of the new IP addresses. Instructions appear in Maintaining Knowledge of Database Server Machines. +
If there are machine entries in the Protection Database for the +machine's previous IP addresses, use the pts rename command to +change them to the new addresses. For instructions, see Changing a Protection Database Entry's Name. +

+ + + +

Rebooting a Server Machine

You can reboot a server machine either by typing the +appropriate commands at its console or by issuing the bos exec +command on a remote machine. Remote rebooting can be more convenient, +because you do not need to leave your present location, but you cannot track +the progress of the reboot as you can at the console. Remote rebooting +is possible because the server machine's operating system recognizes the +BOS Server, which executes the bos exec command, as the local +superuser root. +

Rebooting server machines is part of routine maintenance in some cells, and +some instructions in the AFS documentation include it as a step. It is +certainly not intended to be the standard method for recovering from +AFS-related problems, however, but only a last resort when the machine is +unresponsive and you have tried all other reasonable options. +

Rebooting causes a service outage. If the machine stores volumes, +they are all inaccessible until the reboot completes and the File Server +reattaches them. If the machine is a database server machine, +information from the databases can become unavailable during the reelection of +the synchronization site for each database server process; the VL Server +outage generally has the greatest impact, because the Cache Manager must be +able to access the VLDB to fetch AFS data. +

By convention, a server machine's AFS initialization file includes the +following command to restart the BOS Server after each reboot. It +starts the other AFS server processes listed in the local +/usr/afs/local/BosConfig file. These instructions assume +that the initialization file includes the command. +

   /usr/afs/bin/bosserver &
+

To reboot a file server machine from its console

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the bos shutdown command to shut down all AFS server +processes other than the BOS Server, which terminates safely when you reboot +the machine. Include the -localauth flag because you are +logged in as the local superuser root but do not necessarily have +administrative tokens. For a complete description of the command, see To stop processes temporarily. +
```
   # bos shutdown <machine name> -localauth [-wait]
+
```
+
Reboot the machine. On many system types, the appropriate command +is shutdown, but the appropriate options vary; consult your +UNIX administrator's guide. +
```
    # shutdown
+
```
+

+ + +

To reboot a file server machine remotely

Verify that you are listed in the /usr/afs/etc/UserList file on +the machine you are rebooting. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos shutdown to halt AFS server processes other than +the BOS Server, which terminates safely when you turn off the machine. +For a complete description of the command, see To stop processes temporarily. +
```
   % bos shutdown <machine name>  [-wait]
+
```
+
Issue the bos exec command to reboot the machine +remotely. +
```
   % bos exec <machine name> reboot_command
+
```
+
where +
+
machine name +
Names the file server machine to reboot. +
reboot_command +
Is the rebooting command for the machine's operating system. +The shutdown command is appropriate on many system types, but +consult your operating system documentation. +
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd009.htm b/doc/html/AdminGuide/auagd009.htm new file mode 100644 index 0000000..558586c --- /dev/null +++ b/doc/html/AdminGuide/auagd009.htm @@ -0,0 +1,1420 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Monitoring and Controlling Server Processes

+ + +

One of your most important responsibilities as a system administrator is +ensuring that the processes on file server machines are running +correctly. The BOS Server, which runs on every file server machine, +relieves you of much of the responsibility by constantly monitoring the other +AFS server processes on its machine. It can automatically restart +processes that have failed, ordering the restarts to take interdependencies +into account. +

Because different file server machines run different combinations of +processes, you must define which processes the BOS Server on each file server +machine is to monitor (to learn how, see Controlling and Checking Process Status). +

It is sometimes necessary to take direct control of server process status +before performing routine maintenance or correcting problems that the BOS +Server cannot correct (such as problems with database replication or mutual +authentication). At those times, you control process status through the +BOS Server by issuing bos commands. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + + + + + + +
Examine process status + bos status +
Examine information from the BosConfig file file + bos status with -long flag +
Create a process instance + bos create +
Stop a process + bos stop +
Start a stopped process + bos start +
Stop a process temporarily + bos shutdown +
Start a temporarily stopped process + bos startup +
Stop and immediately restart a process + bos restart +
Stop and immediately restart all processes + bos restart with -bosserver flag +
Examine BOS Server's restart times + bos getrestart +
Set BOS Server's restart times + bos setrestart +
Examine a log file + bos getlog +
Execute a command remotely + bos exec +
+

Brief Descriptions of the AFS Server Processes

This section briefly describes the different server +processes that can run on an AFS server machine. In cells with multiple +server machines, not all processes necessarily run on all machines. +

An AFS server process is referred to in one of three ways, depending on the +context: + +

The output from the bos status command refers to a process by +the name assigned when the bos create command creates its entry in +the /usr/afs/local/BosConfig file. The name can differ from +machine to machine, but it is easiest to maintain the cell if you assign the +same name on all machines. The IBM AFS Quick Beginnings and +the reference page for the bos create command list the conventional +names. Examples are bosserver, kaserver, and +vlserver. +
The process listing produced by the standard ps command +generally matches the process's binary file. Examples of process +binary files are /usr/afs/bin/bosserver, +/usr/afs/bin/kaserver, and /usr/afs/bin/vlserver. +
In most contexts, including most references in the documentation, a +process is referred to as (for example) the Basic OverSeer (BOS) +Server, the Authentication Server, or the Volume +Location Server. +

The following sections specify each name for the process as well as some of +the administrative tasks in which you use the process. For a more +general description of the servers, see AFS Server Processes and the Cache Manager. +

The bosserver Process: the Basic OverSeer Server

+ + +

The bosserver process, which runs on every AFS server machine, +is the Basic OverSeer (BOS) Server responsible for monitoring the other AFS +server processes running on its machine. If a process fails, the BOS +Server can restart it automatically, without human intervention. It +takes interdependencies into account when restarting a process that has +multiple component processes (such as the fs process described in The fs Collection of Processes: the File Server, Volume Server and Salvager). + +

Because the BOS Server does not monitor or restart itself, it does not +appear in the output from the bos status command. It appears +in the ps command's output as +/usr/afs/bin/bosserver. + + +

As a system administrator, you contact the BOS Server when you issue +bos commands to perform the following kinds of tasks. + +

Defining the processes for the BOS Server to monitor by creating entries +in the /usr/afs/local/BosConfig file as described in Controlling and Checking Process Status +
Stopping and starting processes on the file server machines according to +subsequent instructions in this chapter +
Defining your cell's database server machines in the +/usr/afs/etc/CellServDB file as described in Maintaining the Server CellServDB File +
Defining AFS server encryption keys in the /usr/afs/etc/KeyFile +file as described in Managing Server Encryption Keys. +
Granting system administrator privileges with respect to BOS Server, +Volume Server, and Backup Server operations, by adding a user to the +/usr/afs/etc/UserList file as described in Administering the UserList File +
Setting authorization checking requirements on a server machine as +described in Managing Authentication and Authorization Requirements +

The buserver Process: the Backup Server

+ + +

The buserver process, which runs on database server machines, is +the Backup Server. It maintains information about Backup System +configuration and operations in the Backup Database. +

The process appears as buserver in the bos status +command's output, if the conventional name is assigned. It appears +in the ps command's output as +/usr/afs/bin/buserver. + + +

As a system administrator, you contact the Backup Server when you issue any +backup command that manipulates information in the Backup Database, +including those that change Backup System configuration information, that dump +data from volumes to permanent storage, or that restore data to AFS. +See Configuring the AFS Backup System and Backing Up and Restoring AFS Data. +

The fs Collection of Processes: the File Server, Volume Server and Salvager

+ + +

The fs process, which runs on every file server machine, +combines three component processes: File Server, Volume Server and +Salvager. The three components perform independent functions, but are +controlled as a single process for the following reasons. +

They all operate on the same data, namely files and directories stored in +AFS volumes. Combining them as a single process enables them to +coordinate their actions, never attempting simultaneous operations on the same +data that can possibly corrupt it. +
It enables the BOS Server to stop and restart the processes in the +required order. When the File Server fails, the BOS Server stops the +Volume Server and runs the Salvager to correct any corruption that resulted +from the failure. (The Salvager runs only in this special circumstance +or when you invoke it yourself by issuing the bos salvage command +as instructed in Salvaging Volumes.) If only the Volume Server fails, the BOS Server can +restart it without affecting the File Server or Salvager. +

The File Server component handles AFS data at the level of files and +directories, manipulating file system elements as requested by application +programs and the standard operating system commands. Its main duty is +to deliver requested files to client machines and store them again on the +server machine when the client is finished. It also maintains status +and protection information about each file and directory. It runs +continuously during normal operation. + +

The Volume Server component handles AFS data at the level of complete +volumes rather than files and directories. In response to +vos commands, it creates, removes, moves, dumps and restores entire +volumes, among other actions. It runs continuously during normal +operation. + +

The Salvager component runs only after the failure of one of the other two +processes. It checks the file system for internal consistency and +repairs any errors it finds. + + +

The process appears as fs in the bos status +command's output, if the conventional name is assigned. An +auxiliary message reports the status of the File Server or Salvager +component. See Displaying Process Status and Information from the BosConfig File. +

The component processes of the fs process appear individually in +the ps command's output, as follows. There is no entry +for the fs process itself. +

/usr/afs/bin/fileserver +
/usr/afs/bin/volserver +
/usr/afs/bin/salvager +

The Cache Manager contacts the File Server component on your behalf +whenever you access data or status information in an AFS file or directory or +issue file manipulation commands such as the UNIX cp and +ls commands. You can contact the File Server directly by +issuing fs commands that perform the following functions + + +

Administering the ACL of any directory in the file system as described in Managing Access Control Lists +
Installing new partitions for housing AFS volumes, in which case you must +restart the fs process for it to recognize the new partition; +for instructions, see Adding or Removing Disks and Partitions +
Creating and deleting volume mount points in the AFS filespace as +described in Mounting Volumes +
Setting volume quota and displaying information about the space used and +available in a volume or partition as described in Setting and Displaying Volume Quota and Current Size +

+ + +

You contact the Volume Server component when you issue vos +commands that manipulate volumes in any way--creating, removing, +replicating, moving, renaming, converting to different formats, and +salvaging. For instructions, see Managing Volumes. +

The Salvager normally runs automatically in case of a failure. You +can also start it with the bos salvage command as described in Salvaging Volumes. + + +

The kaserver Process: the Authentication Server

+ + +

The kaserver process, which runs on database server machines, is +the Authentication Server responsible for several aspects of AFS +security. It verifies AFS user identity by requiring a password. +It maintains all AFS server encryption keys and user passwords in the +Authentication Database. The Authentication Server's Ticket +Granting Service (TGS) module creates the shared secrets that AFS client and +server processes use when establishing secure connections. +

The process appears as kaserver in the bos status +command's output, if the conventional name is assigned. The +ka string stands for Kerberos Authentication, reflecting +the fact that AFS's authentication protocols are based on Kerberos, which +was originally developed at the Massachusetts Institute of Technology's +Project Athena. +

It appears in the ps command's output as +/usr/afs/bin/kaserver. + + +

As a system administrator, you contact the Authentication Server when you +issue kas commands to perform the following kinds of tasks. +

Setting a user's password. Users normally change their own +passwords, so you probably perform this task only creating a new user account +as described in Creating AFS User Accounts and Changing AFS Passwords. +
Setting the AFS server encryption key in the Authentication Database, +which the TGS uses to seal server tickets; see Managing Server Encryption Keys. +
Granting or revoking system administrator privileges with respect to the +Authentication Server as described in Granting Privilege for kas Commands: the ADMIN Flag. +

The ptserver Process: the Protection Server

+ + +

The ptserver process, which runs on database server machines, is +the Protection Server. Its main responsibility is maintaining the +Protection Database which contains user, machine, and group entries. +The Protection Server allocates AFS IDs and maintains the mapping between them +and names. The File Server consults the Protection Server when +verifying that a user is authorized to perform a requested action. +

The process appears as ptserver in the bos status +command's output, if the conventional name is assigned. It appears +in the ps command's output as +/usr/afs/bin/ptserver. + + +

As a system administrator, you contact the Protection Server when you issue +pts commands to perform the following kinds of tasks. +

Creating a new user, machine, or group entry in the Protection Database as +described in Administering the Protection Database +
Adding or removing group members or otherwise manipulating Protection +Database entries as described in Administering the Protection Database +
Granting or revoking system administrator privilege by changing the +membership of the system:administrators group as described in +Administering the system:administrators Group +

The runntp Process

+ + + +

The runntp process, which runs on every server machine, is a +controller program for the Network Time Protocol Daemon (NTPD), which +synchronizes the hardware clocks on server machines. You need to run +the runntp process if you are not already running NTP or another +time synchronization protocol on your server machines. +

The clocks on database server machines need to be synchronized because +AFS's distributed database technology (Ubik) works properly only when the +clocks agree within a narrow range of variation (see Configuring the Cell for Proper Ubik Operation). The clocks on file server machines need to be +correct not only because the File Server sets modification time stamps on +files, but because in the conventional configuration they serve as the time +source for AFS client machines. +

The process appears as runntp in the bos status +command's output, if the conventional name is assigned. It appears +in the output from the ps command as +/usr/afs/bin/runntp. The ps command's output +also includes an entry called ntpd; its exact form depends on +the arguments you provide to the runntp command. + + +

As a system administrator, you do not contact the NTPD directly once you +have installed it according to the instructions in the IBM AFS Quick +Beginnings. +

The upserver and upclient Processes: the Update Server

+ + + +

The Update Server has two separate parts, each of which runs on a different +type of server machine. The upserver process is the server +portion of the Update Server. Its function depends on which edition of +AFS you use: +

With both the United States and international editions, it runs on the +binary distribution machine of each system type you use as a server machine, +distributing the contents of each one's /usr/afs/bin directory +to the other server machines of that type. This guarantees that all +machines have the same version of AFS binaries. (For a list of the +binaries, see Binaries in the /usr/afs/bin Directory.) +
In you use the United States edition of AFS, it also runs on the +cell's system control machine, distributing the contents of its +/usr/afs/etc directory to all the other server machines in order to +synchronize the configuration files stored in that directory. (For a +list of the configuration files, see Common Configuration Files in the /usr/afs/etc Directory.) +

The upclient process is the client portion of the Update Server, +and like the server portion its function depends on the AFS edition in +use. +

It runs on every server machine that is not a binary distribution machine, +referencing the binary distribution machine of its system type as the source +for updates to the binaries in the /usr/afs/bin directory. +The conventional process name to assign is upclientbin. +
If you use the United States edition of AFS, another instance of the +process runs on every server machine except the system control machine. +It references the system control machine as the source for updates to the +common configuration files in the /usr/afs/etc directory. +The conventional process name to assign is upclientetc. +

In output from the bos status command, the server portion +appears as upserver and the client portions as +upclientbin and upclientetc, if the conventional names +are assigned. In the output from the ps command, the server +portion appears as /usr/afs/bin/upserver and the client portions as +/usr/afs/bin/upclient. + + +

You do not contact the Update Server directly once you have installed +it. It operates automatically whenever you use bos commands +to change the files that it distributes. +

The vlserver Process: the Volume Location Server

+ + +

The vlserver process, which runs on database server machines, is +the Volume Location (VL) Server that automatically tracks which file server +machines house each volume, making its location transparent to client +applications. +

The process appears as vlserver in the bos status +command's output, if the conventional name is assigned. It appears +in the ps command's output as +/usr/afs/bin/vlserver. + + + +

As a system administrator, you contact the VL Server when you issue any +vos command that changes the status of a volume (it records the +status changes in the VLDB). +

Controlling and Checking Process Status

To define the AFS server processes that run on a server +machine, use the bos create command to create entries for them in +the local /usr/afs/local/BosConfig file. The BOS Server +monitors the processes listed in the BosConfig file that are marked +with the Run status flag, and automatically attempts to restart +them if they fail. After creating process entries, you use other +commands from the bos suite to stop and start processes or change +the status flag as desired. +

Never edit the BosConfig file directly rather than using +bos commands. Similarly, it is not a good practice to run +server processes without listing them in the BosConfig file, or to +stop them using process termination commands such as the UNIX kill +command. +

The Information in the BosConfig File

+ + +

A process's entry in the BosConfig file includes the +following information: +

The process's name. The recommended conventional names are +defined in both the IBM AFS Quick Beginnings and Creating and Removing Processes. The name of a simple process usually matches the +name of its binary file (for example, ptserver for the Protection +Server). +
Its type, which is one of the following: +
+ + +
simple +
A process that runs independently of any other on the server +machine. If several simple processes fail at the same time, the BOS +Server can restart them in any order. All standard AFS processes except +the fs process are simple. +
fs + + + + + +
A process type reserved for the server process for which the conventional +name is also fs. This process combines three +components: the File Server, the Volume Server, and the Salvager. + + +
cron +
A process that runs at a defined time rather than continuously. +There are no standard processes of this type. +
+ + + + +
Its status flag, which tells the BOS Server whether it performs the +following two actions with respect to the process: +
- Start the process during BOS Server initialization +
- Restart the process if it (the process) fails +
The two possible values are Run (which directs the BOS Server +to perform these actions) and NotRun (which directs the BOS Server +to ignore the process). The BOS Server itself never changes the setting +of this flag, even if the process fails repeatedly. Also, this flag is +for internal use only; it does not appear in the bos status +command's output. +
Its command parameters, which are the commands that the BOS Server runs to +start the process. + +
- A simple processes has one: the complete pathname to its binary file +
- The fs process has three: the complete pathnames to each +of the three component processes (/usr/afs/bin/fileserver, +/usr/afs/bin/volserver, and /usr/afs/bin/salvager) +
- A cron process has two: the first the complete pathname to its +binary file, the second the time at which the BOS Server runs it +
+

In addition to process definitions, the BosConfig file also +records automatic restart times for processes that have new binaries, and for +all server processes including the BOS Server. See Setting the BOS Server's Restart Times. +

How the BOS Server Uses the Information in the BosConfig File

+ + + +

Whenever the BOS Server starts or restarts, it reads the +BosConfig file to learn which processes it is to start and +monitor. It transfers the information into kernel memory and does not +read the BosConfig file again until it next restarts. This +implies that the BOS Server's memory state can change independently of +the BosConfig file. You can, for example, stop a process but +leave its status flag in the BosConfig file as Run, or +start a process even though its status flag in the BosConfig file +is NotRun. +

About Starting and Stopping the Database Server Processes

+ + + + + + + +

When you start or stop a database server process (Authentication Server, +Backup Server, Protection Server, or Volume Location Server) for more than a +short time, you must follow the instructions in the IBM AFS Quick +Beginnings for installing or removing a database server machine. +Here is a summary of the tasks you must perform to preserve correct AFS +functioning. +

Start or stop all four database server processes on that machine. +All AFS server processes and the Cache Manager processes expect all four +database server processes to be running on each machine listed in the +CellServDB file. There is no way to indicate in the file +that a machine is running only some of the database server processes. +
Add or remove the machine in the /usr/afs/etc/CellServDB file +on all server machines and the /usr/vice/etc/CellServDB file on all +client machines. +
Restart the database server processes on the other database server +machines to force an election of a new Ubik coordinator for each one. +

About Starting and Stopping the Update Server

+ +

In the conventional cell configuration, one server machine of each system +type acts as a binary distribution machine, running the server portion of the +Update Server (upserver process) to distribute the contents of its +/usr/afs/bin directory. The other server machines of its +system type run an instance of the Update Server client portion (by convention +called upclientbin) that references the binary distribution +machine. +

If you run the United States edition of AFS, it is conventional for the +first server machine you install to act as the system control machine, running +the server portion of the Update Server (upserver process) to +distribute the contents of its /usr/afs/etc directory. All +other server machines run an instance of the Update Server client portion (by +convention called upclientetc) that references the system control +machine. +

+
Note: If you are using the international edition of AFS, do not use the Update +Server to distribute the contents of the /usr/afs/etc directory +(you do not run a system control machine). Ignore all references to the +process in this chapter. +
+

It is simplest not to move binary distribution or system control +responsibilities to a different machine unless you completely decommission a +machine that is currently serving in one of those roles. Running the +Update Server usually imposes very little processing load. If you must +move the functionality, perform the following related tasks. +

If you replace the system control machine, you must stop the +upclientetc process on every other server machine and define a new +one that references the new system control machine. +
If you replace a binary distribution machine, you must stop the +upclientbin process on every other server machine of its system +type and define a new one that references the new binary distribution machine +(unless you are no longer running any server machines of that system +type). +

Displaying Process Status and Information from the BosConfig File

To display the status of the AFS server processes on a +server machine, issue the bos status command. Adding the +-long flag displays most of the information from each +process's entry in the BosConfig file, including its type and +command parameters. It also displays a warning message if the mode bits +on files and subdirectories in the /usr/afs directory do not match +the expected values. +

To display the status of server processes and their BosConfig entries

+ + + + + + + + +

Issue the bos status command. +
```
   % bos status <machine name>  [<server process name>⁺]  [-long]
+
```
+
where +
+
stat +
Is the shortest acceptable abbreviation of status. +
machine name +
Specifies the file server machine for which to display process +status. +
server process name +
Names each process for which to display status, using the name assigned +when its entry was defined with the bos create command. Omit +this argument to display the status of all server processes. +
-long +
Displays, in addition to status, information from the process's entry +in the BosConfig file: its type, its status flag, its command +parameters, the associated notifier program, and so on. +
+

The output includes an entry for each process and uses one of the following +strings to indicate the process's status: +

currently running normally indicates that the process is +running and its status flag in the BosConfig file is +Run. For cron entries, this message indicates that the +command is still scheduled to run, not necessarily that it is actually running +when the bos status command was issued. +
temporarily enabled indicates that the process is running but +that its status flag in the BosConfig file is +NotRun. The most common reason is that a system +administrator has used the bos startup command to start the +process. +
temporarily disabled indicates that the process is not running +even though its status flag in the BosConfig file is +Run. The most common reasons are either that a system +administrator has used the bos shutdown command to stop the process +or that the BOS Server ceased trying to restart the process after numerous +failed attempts. In the latter case, a supplementary message +appears: stopped for too many errors. +
disabled indicates that the process is not running and that its +status flag in the BosConfig file is NotRun. The +BOS Server is not monitoring the process. Only a system administrator +can set the flag this way; the BOS Server never does. +

The output for the fs process always includes a message marked +Auxiliary status, which can be one of the following: +

file server running indicates that the File Server and Volume +Server components of the File Server process are running normally. +
salvaging file system indicates that the Salvager is running, +which usually implies that the File Server and Volume Server are temporarily +disabled. The BOS Server restarts them as soon as the Salvager is +finished. +

The output for a cron process also includes an Auxiliary status +message to report when the command is scheduled to run next; see the +example that follows. +

The output for any process can include the supplementary message has +core file to indicate that at some point the process failed and +generated a core file in the /usr/afs/logs directory. In +most cases, the BOS Server is able to restart the process and it is +running. +

The following example includes a user-defined cron entry called +backupusers: +

   % bos status fs3.abc.com
+   Instance kaserver, currently running normally.
+   Instance ptserver, currently running normally.
+   Instance vlserver, has core file, currently running normally.
+   Instance buserver, currently running normally.
+   Instance fs, currently running normally.
+       Auxiliary status is: file server running.
+   Instance upserver, currently running normally.
+   Instance runntp, currently running normally.
+   Instance backupusers, currently running normally.
+       Auxiliary status is: run next at Mon Jun 7 02:00:00 1999.
+

If you include the -long flag to the bos status +command, a process's entry in the output includes the following +additional information from the BosConfig file: +

The process's type (simple, fs, or +cron). +
The day and time the process last started or restarted. +
The number of proc starts, which is how many times the BOS +Server has started or restarted the process since it started itself. +
The Last exit time when the process (or one of the component +processes in the fs process) last terminated. This line does +not appear if the process has not terminated since the BOS Server +started. +
The Last error exit time when the process (or one of the +component processes in the fs process) last failed due to an +error. A further explanation such as due to shutdown request +sometimes appears. This line does not appear if the process has not +failed since the BOS Server started. +
Each command that the BOS Server invokes to start the process, as +specified by the -cmd argument to the bos create +command. +
The pathname of the notifier program that the BOS Server invokes when the +process terminates (if any), as specified by the -notifier argument +to the bos create command. +

In addition, if the BOS Server has found that the mode bits on certain +files and directories under /usr/afs deviate from what it expects, +it prints the following warning message: +

   Bosserver process reports inappropriate access on server directories
+

The expected protections for the directories and files in the +/usr/afs directory are as follows. A question mark indicates +that the BOS Server does not check the mode bit. See the IBM AFS +Quick Beginnings for more information about setting the protections on +these files and directories. +
+ + + + + + + + + + +
/usr/afs + drwxr?xr-x +
/usr/afs/backup + drwx???--- +
/usr/afs/bin + drwxr?xr-x +
/usr/afs/db + drwx???--- +
/usr/afs/etc + drwxr?xr-x +
/usr/afs/etc/KeyFile + -rw????--- +
/usr/afs/etc/UserList + -rw?????-- +
/usr/afs/local + drwx???--- +
/usr/afs/logs + drwxr?xr-x +
+

The following illustrates the extended output for the fs process +running on the machine fs3.abc.com: +

   % bos status fs3.abc.com fs -long
+   Instance fs, (type is fs), currently running normally.
+       Auxiliary status is file server running
+   Process last started at Mon May 3 8:29:19 1999 (3 proc starts)
+   Last exit at Mon May 3 8:29:19 1999
+   Last error exit at Mon May 3 8:29:19 1999, due to shutdown request
+   Command 1 is '/usr/afs/bin/fileserver'
+   Command 2 is '/usr/afs/bin/volserver'
+   Command 3 is '/usr/afs/bin/salvager'
+

Creating and Removing Processes

+ + + + + + + + +

To start a new AFS server process on a server machine, issue the bos +create command, which creates an entry in the +/usr/afs/local/BosConfig file, sets the process's status flag +to Run both in the file and in the BOS Server's memory, and +starts it running immediately. The binary file for the new process must +already be installed, by convention in the /usr/afs/bin directory +(see Installing New Binaries). +

To stop a process permanently, first issue the bos stop command, +which changes the process's status flag to NotRun in both the +BosConfig file and the BOS Server's memory; it is marked +as disabled in the output from the bos status +command. If desired, issue the bos delete command to remove +the process's entry from the BosConfig file; the process +no longer appears in the bos status command's output. +

+
Note: If you are starting or stopping a database server process in the manner +described in this section, follow the complete instructions in the IBM +AFS Quick Beginnings for creating or removing a database server +machine. If you run one database server process on a given machine, you +must run them all; for more information, see About Starting and Stopping the Database Server Processes. Similarly, if you are stopping the +upserver process on the system control machine or a binary +distribution machine, you must complete the additional tasks described in About Starting and Stopping the Update Server. +
+

To create and start a new process

+ + + + + + + + +

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
(Optional) Verify that the process's binaries are +installed in the /usr/afs/bin directory on this machine. If +necessary, login at the console or telnet to the machine and list the contents +of the /usr/afs/bin directory. +
If the binaries are not present, install them on the binary distribution +machine of the appropriate system type, and wait for the Update Server to copy +them to this machine. For instructions, see Installing New Binaries. +
```
   % ls /usr/afs/bin
+
```
+
Issue the bos create command to create an entry in +the BosConfig file and start the process. +
```
   % bos create <machine name> <server process name>   \
+             <server type> <command lines>⁺ [ -notifier <Notifier program>]
+
```
+
where +
+
cr +
Is the shortest acceptable abbreviation of create. +
machine name +
Specifies the file server machine on which to create the process. +
server process name +
Names the process to create and start. For simple processes, the +conventional value is the name of the process's binary file. It is +best to use the same name on every server machine that runs the +process. The following is a list of the conventional names for simple +and fs-type processes (there are no standard cron processes). +
- buserver for the Backup Server +
- fs for the process that combines the File Server, Volume +Server, and Salvager +
- kaserver for the Authentication Server +
- ptserver for the Protection Server +
- runntp for the controller process for the Network Time Protocol +Daemon +
- upclientbin for the client portion of the Update Server that +references the binary distribution machine of this machine's system type +
- upclientetc for the client portion of the Update Server that +references the system control machine +
- vlserver for the Volume Location (VL) Server +
+
server type +
Defines the process's type. Choose one of the following +values: +
- cron for a cron process +
- fs for the process named fs +
- simple for all other processes listed as acceptable values for +the server process name argument +
+
command lines +
Specifies each command the BOS Server runs to start the process. +Specify no more than six commands (which can include the command's +options, in which case the entire string is surrounded by double quotes); +any additional commands are ignored. +
For a simple process, provide the complete pathname of the process's +binary file on the local disk (for example, /usr/afs/bin/ptserver +for the Protection Server). If including any of the initialization +command's options, surround the entire command in double quotes (" +"). The upclient process has a required argument, and +the commands for all other processes take optional arguments. + +
For the fs process, provide the complete pathname of the local +disk binary file for each of the component processes: +fileserver, volserver, and salvager, in that +order. The standard binary directory is /usr/afs/bin. +If including any of an initialization command's options, surround the +entire command in double quotes (" "). + +
For a cron process, provide two parameters: + +
- The complete local disk pathname of either an executable file or a command +from one of the AFS suites (complete with all of the necessary +arguments). Surround this parameter with double quotes (" ") +if it contains spaces. +
- A specification of when the BOS Server executes the file or command +indicated by the first parameter. There are three acceptable +values: +
  - The string now, which directs the BOS Server to execute the +file or command immediately and only once. It is usually simpler to +issue the command directly or issue the bos exec command. +
  - A time of day. The BOS Server executes the file or command daily at +the indicated time. Separate the hours and minutes with a colon +(hh:MM), and use either 24-hour format, or a value +in the range from 1:00 through 12:59 with +the addition of am or pm. For example, both +14:30 and "2:30 pm" indicate 2:30 in +the afternoon. Surround this parameter with double quotes (" +") if it contains a space. +
  - A day of the week and time of day, separated by a space and surrounded +with double quotes (" "). The BOS Server executes the file +or command weekly at the indicated day and time. For the day, provide +either the whole name or the first three letters, all in lowercase letters +(sunday or sun, thursday or thu, +and so on). For the time, use the same format as when specifying the +time alone. +
  +
+
-notifier +
Specifies the pathname of a program that the BOS Server runs when the +process terminates. For more information on notifier programs, see the +bos create command reference page in the IBM AFS +Administration Reference. +
+

The following example defines and starts the Protection Server on the +machine db2.abc.com: +

   
+   % bos create db2.abc.com ptserver simple /usr/afs/bin/ptserver 
+   
+

The following example defines and starts the fs process on the +machine fs6.abc.com. +

   
+   % bos create fs6.abc.com fs fs /usr/afs/bin/fileserver   \
+        /usr/afs/bin/volserver /usr/afs/bin/salvager
+    
+

The following example defines and starts a cron process called +backupuser process on the machine +fs3.abc.com, scheduling it to run each day at +3:00 a.m. +

   % bos create fs3.abc.com backupuser cron  "/usr/afs/bin/vos backupsys -prefix user -local" 3:00 
+

To stop a process and remove it from the BosConfig file

+ + + + + + + +

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos stop command to change each +process's status flag in the BosConfig file to +NotRun and to stop it. You must issue this command even for +cron processes that you wish to remove from the BosConfig file, +even though they do not run continuously. For a detailed description of +this command, see To stop a process by changing its status to NotRun. +
```
   
+   % bos stop <machine name> <server process name>⁺ [-wait]
+   
+
```
+
Issue the bos delete command to remove each +process from the BosConfig file. +
```
   % bos delete <machine name> <server process name>⁺
+
```
+
where +
+
d +
Is the shortest acceptable abbreviation of delete. +
machine name +
Specifies the server machine on which to remove processes from the +BosConfig file. +
server process name +
Names each process entry to remove from the BosConfig +file. Provide the same names as in Step 2. +
+

Stopping and Starting Processes Permanently

+ + + + +

To stop a process so that the BOS Server no longer attempts to monitor it, +issue the bos stop command. The process's status flag +is set to NotRun in both the BOS Server's memory and in the +BosConfig file. The process does not run again until you +issue the bos start command, which sets its status flag back to +Run in both the BOS Server's memory and in the +BosConfig file. (You can also use the bos startup +command to start the process again without changing its status flag in the +BosConfig file; see Stopping and Starting Processes Temporarily.) +

There is no entry for the BOS Server in the BosConfig file, so +the bos stop and bos start commands do not control +it. To stop and immediately restart the BOS Server along with all other +processes, use the -bosserver flag to the bos restart +command as described in Stopping and Immediately Restarting Processes. +

To stop a process by changing its status to NotRun

+ + + + + + +

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos stop command to stop each process and set its +status flag to NotRun in the BosConfig file and the BOS +Server's memory. +
```
   % bos stop <machine name> <server process name>⁺ [-wait]
+
```
+
where +
+
sto +
Is the shortest acceptable abbreviation of stop. +
machine name +
Specifies the server machine on which to stop the process. +
server process name +
Names each process to stop, using the name assigned when its entry was +defined with the bos create command. +
-wait +
Delays the return of the command shell prompt until all specified +processes have stopped. If you omit the flag, the prompt returns almost +immediately, even if all processes are not yet stopped. +
+

To start processes by changing their status flags to Run

+ + + + + +

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos start command to change each +process's status flag to Run in both the BosConfig +file and the BOS Server's memory and to start it. +
```
   %  bos start <machine name> <server process name>⁺
+
```
+
where +
+
start +
Must be typed in full. +
machine name +
Specifies the server machine on which to start running each +process. +
server process name +
Specifies each process to start on machine name. Use the +name assigned to the process at creation. +
+

Stopping and Starting Processes Temporarily

It is sometimes necessary to halt a process temporarily (for +example, to make slight configuration changes or to perform +maintenance). The commands described in this section change a +process's status in the BOS Server's memory only; the effect is +immediate and lasts until you change the memory state again (or until the BOS +Server restarts, at which time it starts the process according to its entry in +the BosConfig file). +

To stop a process temporarily by changing its status flag in BOS Server +memory to NotRun, use the bos shutdown command. +To restart a stopped process by changing its status flag in the BOS +Server's memory to Run, use the bos startup +command. The process starts regardless of its status flag in the +BosConfig file. You can also use the bos startup +command to start all processes marked with status flag Run in the +BosConfig file, as described in the following instructions. +

Because the bos startup command starts a process without +changing it status flag in the BosConfig file, it is useful for +testing a server process without enabling it permanently. To stop and +start processes by changing their status flags in the BosConfig +file, see Stopping and Starting Processes Permanently; to stop and immediately restart a process, see Stopping and Immediately Restarting Processes. +
Note: Do not temporarily stop a database server process on all machines at +once. Doing so makes the database completely unavailable. +
+ + +

To stop processes temporarily

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos shutdown command to stop each process +by changing its status flag in the BOS Server's memory to +NotRun. +
```
   % bos shutdown <machine name> [<instances>⁺] [-wait]
+
```
+
where +
+
sh +
Is the shortest acceptable abbreviation of shutdown. +
machine name +
Specifies the server machine on which to stop processes +temporarily. +
instances +
Specifies each process to stop temporarily. Use the name assigned +to the process at creation. +
-wait +
Delays the return of the command shell prompt until all specified +processes have actually stopped. If you omit the flag, the prompt +returns almost immediately, even if all processes are not yet stopped. +
+

+ + +

To start all stopped processes that have status flag Run in the BosConfig file

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos startup command to start each process on a +machine that has status flag Run in the BosConfig file +by changing its status flag in the BOS Server's memory from +NotRun to Run. +
```
   % bos startup <machine name>
+
```
+
where +
+
startup +
Must be typed in full. +
machine name +
Specifies the server machine on which you wish to start all processes that +have status flag Run in the BosConfig file. +
+

To start specific processes

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos startup command to start specific processes by +changing their status flags in the BOS Server's memory to Run +without changing their status flags in the BosConfig file. +
```
   % bos startup <machine name> <instances>⁺
+
```
+
where +
+
startup +
Must be typed in full. +
machine name +
Names the server machine on which to start processes. +
instances +
Specifies each process to start. Use the name assigned to the +process at creation. +
+

Stopping and Immediately Restarting Processes

+ + +

Although by default the BOS Server checks each day for new installed binary +files and restarts the associated processes, it is sometimes desirable to stop +and restart processes immediately. The bos restart command +provides this functionality, starting a completely new instance of each +affected process: +

To stop and restart the BOS Server, which then restarts all processes +marked with the Run status flag in the BosConfig file, +include the -bosserver flag. +
To stop and restart all processes marked with the Run status +flag in the BosConfig file, include the -all +flag. The BOS Server does not restart +
To stop and restart specific processes regardless of the setting of their +status flags in the BosConfig file, specify the name of each +process to restart. +

Restarting processes causes a service outage. It is usually best to +schedule restarts for periods of low usage. The BOS Server +automatically restarts all processes once a week, to reduce the potential for +the core leaks that can develop as any process runs for an extended time; +see Setting the BOS Server's Restart Times. + + +

+ + + + + +

To stop and restart all processes including the BOS Server

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos restart command with the -bosserver +flag to stop and restart the BOS Server, which restarts every process marked +with status flag Run in the BosConfig file. +
```
   % bos restart <machine name>  -bosserver
+
```
+
where +
+
res +
Is the shortest acceptable abbreviation of restart. +
machine name +
Specifies the server machine on which to restart all processes. +
-bosserver +
Stops the BOS Server and all processes running on the machine. A +new BOS Server instance starts; it then starts new instances of all +processes marked with status flag Run in the BosConfig +file. +
+

+ + + + +

To stop and immediately restart all processes except the BOS Server

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos restart command with the -all flag to +stop and immediately restart every process marked with status flag +Run in the BosConfig file. The BOS Server does +not restart. +
```
   % bos restart <machine name> -all
+
```
+
where +
+
res +
Is the shortest acceptable abbreviation of restart. +
machine name +
Specifies the server machine on which to stop and restart +processes. +
-all +
Stops and immediately restarts all processes marked with status flag +Run in the BosConfig file. +
+

+ + + + +

To stop and immediately restart specific processes

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos restart command to stop and immediately restart +one or more specified processes, regardless of their status flag setting in +the BosConfig file. +
```
   % bos restart <machine name> <instances>⁺
+
```
+
where +
+
res +
Is the shortest acceptable abbreviation of restart. +
machine name +
Names the server machine on which to restart the specified +processes. +
instances +
Specifies each process to stop and immediately restart. Use the +name assigned to the process at creation. +
+

Setting the BOS Server's Restart Times

+ + + + + + + + + +

The BOS Server by default restarts once a week, and the new instance +restarts all processes marked with status flag Run in the local +/usr/afs/local/BosConfig file (this is equivalent to issuing the +bos restart command with the -bosserver flag). +The default restart time is Sunday at 4:00 a.m. The weekly +restart is designed to minimize core leaks, which can develop as a +process continues to allocate virtual memory but does not free it +again. When the memory is completely exhausted, the machine can no +longer function correctly. +

The BOS Server also by default checks once a day for any newly installed +binary files. If it finds that the modification time stamp on a +process's binary file in the /usr/afs/bin directory is more +recent than the time at which the process last started, it restarts the +process so that a new instance starts using the new binary file. The +default binary-checking time is 5:00 a.m. +

Because restarts can cause outages during which the file system is +inaccessible, the default times for restarts are in the early morning when +usage is likely to be lowest. Restarting a database server process on +any database server machine usually makes the entire system unavailable to +everyone for a brief time, whereas restarting other types of processes +inconveniences only users interacting with that process on that +machine. The longest outages typically result from restarting the +fs process, because the File Server must reattach all +volumes. + + + +

The BosConfig file on each file server machine records the two +restart times. To display the current setting, issue the bos +getrestart command. To reset a time, use the bos +setrestart command. + + + +

To display the BOS Server restart times

Issue the bos getrestart command to display the automatic +restart times. +
```
   % bos getrestart <machine name>
+
```
+
where +
+
getr +
Is the shortest acceptable abbreviation of getrestart. +
machine name +
Specifies the server machine for which to display the restart +times. +
+

+ + + +

To set the general or binary restart time

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+

Issue the bos setrestart command with the -general +flag to set the general restart time or the -newbinary flag to set +the binary restart time. The command accepts only one of the flags at a +time. +

   % bos setrestart <machine name> "<time to restart server>" [-general]  [-newbinary]
+

where +

setr +

Is the shortest acceptable abbreviation of setrestart. +

machine name +

Specifies the server machine. +

time to restart server +

Sets when the BOS Server restarts itself (if combined with the +-general flag) or any process with a new binary file (if combined +with the -newbinary flag). Provide one of the following +types of values: +

The string never, which directs the BOS Server never to perform +the indicated type of restart. +
A time of day (the conventional type of value for the binary restart +time). Separate the hours and minutes with a colon +(hh:MM), and use either 24-hour format, or a value +in the range from 1:00 through 12:59 with +the addition of am or pm. For example, both +14:30 and "2:30 pm" indicate 2:30 in +the afternoon. Surround this parameter with double quotes (" +") if it contains a space. +
A day of the week and time of day, separated by a space and surrounded +with double quotes (" "). This is the conventional type of +value for the general restart. For the day, provide either the whole +name or the first three letters, all in lowercase letters (sunday +or sun, thursday or thu, and so on). +For the time, use the same format as when specifying the time alone. +

If desired, precede a time or day and time definition with the string +every or at. These words do not change the +meaning, but possibly make the output of the bos getrestart command +easier to understand. +
Note: If the specified time is within one hour of the current time, the BOS Server +does not perform the restart until the next eligible time (the next day for a +time or next week for a day and time). +
+

-general +

Sets the general restart time when the BOS Server restarts itself. +

-newbinary +

Sets the restart time for processes with new binary files. +

Displaying Server Process Log Files

+ + + + + + + + + + + + + + + + + + +

The /usr/afs/logs directory on each file server machine contains +log files that detail interesting events that occur during normal operation of +some AFS server processes. The self-explanatory information in the log +files can help you evaluate process failures and other problems. To +display a log file remotely, issue the bos getlog command. +You can also establish a connection to the server machine and use a text +editor or other file display program (such as the cat +command). +
Note: Log files can grow unmanageably large if you do not periodically shutdown and +restart the database server processes (for example, if you disable the general +restart time). In this case it is a good policy periodically to issue +the UNIX rm command to delete the current log file. The +server process automatically creates a new one as needed. +
+ + +

To examine a server process log file

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos getlog command to display a log file. +
```
   % bos getlog  <machine name>  <log file to examine>
+
```
+
where +
+
getl +
Is the shortest acceptable abbreviation of getlog. +
machine name +
Specifies the server machine from which to display the log file. +
log file to examine +
Names the log file to be displayed. Provide one of the following +file names to display the indicated log file from the /usr/afs/logs +directory. +
- AuthLog for the Authentication Server log file +
- BackupLog for the Backup Server log file +
- BosLog for the BOS Server log file +
- FileLog for the File Server log file +
- SalvageLog for the Salvager log file +
- VLLog for the Volume Location (VL) Server log file +
- VolserLog for the Volume Server log file +
+
You can provide a full or relative pathname to display a file from another +directory. Relative pathnames are interpreted relative to the +/usr/afs/logs directory. +
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd010.htm b/doc/html/AdminGuide/auagd010.htm new file mode 100644 index 0000000..9b228fa --- /dev/null +++ b/doc/html/AdminGuide/auagd010.htm @@ -0,0 +1,3623 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Managing Volumes

This chapter explains how to manage the volumes stored on +file server machines. The volume is the designated unit of +administration in AFS, so managing them is a large part of the +administrator's duties. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Create read/write volume + vos create +
Create read-only volume + vos addsite and vos release +
Create backup volume + vos backup +
Create many backup volumes at once + vos backupsys +
Examine VLDB entry + vos listvldb +
Examine volume header + vos listvol +
Examine both VLDB entry and volume header + vos examine +
Display volume's name + fs listquota or fs examine +
Display volume's ID number + fs examine or vos examine or +vos listvol +
Display partition's size and space available + vos partinfo +
Display volume's location + fs whereis or vos examine +
Create mount point + fs mkmount +
Remove mount point + fs rmmount +
Display mount point + fs lsmount +
Move read/write volume + vos move +
Synchronize VLDB with volume headers + vos syncvldb and vos syncserv +
Set volume quota + fs setvol or fs setquota +
Display volume quota + fs quota or fs listquota or +fs examine +
Display volume's current size + fs listquota or fs examine +
Display list of volumes on a machine/partition + vos listvol +
Remove read/write volume + vos remove and fs rmmount +
Remove read-only volume + vos remove +
Remove backup volume + vos remove and fs rmmount +
Remove volume; no VLDB change + vos zap +
Remove read-only site definition + vos remsite +
Remove VLDB entry; no volume change + vos delentry +
Dump volume + vos dump +
Restore dumped volume + vos restore +
Rename volume + vos rename, fs rmmount and fs +mkmount +
Unlock volume + vos unlock +
Unlock multiple volumes + vos unlockvldb +
Lock volume + vos lock +
+

About Volumes

+ +

An AFS volume is a logical unit of disk space that functions +like a container for the files in an AFS directory, keeping them all together +on one partition of a file server machine. To make a volume's +contents visible in the cell's file tree and accessible to users, you +mount the volume at a directory location in the AFS filespace. The +association between the volume and its location in the filespace is called a +mount point, and because of AFS's internal workings it looks +and acts just like a standard directory element. Users can access and +manipulate a volume's contents in the same way they access and manipulate +the contents of a standard UNIX directory. For more on the relationship +between volumes and directories, see About Mounting Volumes. +

Many of an administrator's daily activities involve manipulating +volumes, since they are the basic storage and administrative unit of +AFS. For a discussion of some of the ways volumes can make your job +easier, see How Volumes Improve AFS Efficiency. +

The Three Types of Volumes

There are three types of volumes in AFS, as described in the +following list: +

The single read/write version of a volume houses the modifiable +versions of the files and directories in that volume. + +It is often referred to as the read/write source because volumes of +the other two types are derived from it by a copying procedure called +cloning. For instructions on creating read/write volumes, +see Creating Read/write Volumes. +
A read-only volume is a copy of the read/write source volume +and can exist at multiple sites (a site is a particular partition +on a particular file server machine). + + + +Placing the same data at more than one site is called +replication; see How Volumes Improve AFS Efficiency. As the name suggests, a +read-only volume's contents do not change automatically as the read/write +source changes, but only when an administrator issues the vos +release command. For users to have a consistent view of the AFS +filespace, all copies of the read-only volume must match each other and their +read/write source. All read-only volumes share the same name, which is +derived by adding the .readonly extension to the read/write +source's name. For instructions on creating of read-only volumes, +see Replicating Volumes (Creating Read-only Volumes). +

A backup volume is a clone of the read/write source volume and +is stored at the same site as the source. + +A backup version is useful because it records the state of the read/write +source at a certain time, allowing recovery of data that is later mistakenly +changed or deleted (for further discussion see How Volumes Improve AFS Efficiency). A backup volume's name is derived by adding +the .backup extension to the read/write source's +name. For instructions on creating of backup volumes, see Creating Backup Volumes. +

Note:

A backup volume is not the same as the backup of a volume transferred to tape +using the AFS Backup System, although making a backup version of a volume is +usually a stage in the process of backing up the volume to tape. For +information on backing up a volume using the AFS Backup System, see Backing Up Data. +

As noted, the three types of volumes are related to one another: +read-only and backup volumes are both derived from a read/write volume through +a process called cloning. Read-only and backup volumes are exact copies +of the read/write source at the time they are created. +

How Volumes Improve AFS Efficiency

+ +

Volumes make your cell easier to manage and more efficient in the following +three ways: +

Volumes are easy to move between partitions, on the same or different +machines, because they are by definition smaller than a partition. + +Perhaps the most common reasons to move volumes are to balance the load among +file server machines or to take advantage of greater disk capacity on certain +machines. You can move volumes as often as necessary without disrupting +user access to their contents, because the move procedure makes the contents +unavailable for only a few seconds. The automatic tracking of volume +locations in the Volume Location Database (VLDB) assures that access remains +transparent. For instructions on moving volumes, see Moving Volumes. +
Volumes are the unit of replication in AFS. + + +Replication refers to creating a read-only clone from the +read/write source and distributing of the clone to one or more sites. +Replication improves system efficiency because more than one machine can fill +requests for popular files. It also boosts system reliability by +helping to keep data available in the face of machine or server process +outage. In general, volumes containing popular application programs and +other files that do not change often are the best candidates for replication, +but you can replicate any read/write volume. See Replicating Volumes (Creating Read-only Volumes). +
Volumes are the unit of backup in AFS, in two senses. + +You can create a backup volume version to preserves the state of a read/write +source volume at a specified time. You can mount the backup version in +the AFS filespace, enabling users to restore data they have accidentally +changed or deleted without administrator assistance, which frees you for more +important jobs. If you make a new backup version of user volumes once a +day (presumably overwriting the former backup), then users are always be able +to retrieve the previous day's version of a file. For +instructions, see Creating Backup Volumes. +
Backup also refers to using the AFS Backup System to store permanent copies +of volume contents on tape or in a special backup data. See Configuring the AFS Backup System and Backing Up and Restoring AFS Data. +

Volume Information in the VLDB

The Volume Location Database (VLDB) includes entries for +every volume in a cell. Perhaps the most important information in the +entry is the volume's location, which is key to transparent access to AFS +data. When a user opens a file, the Cache Manager consults the Volume +Location (VL) Server, which maintains the VLDB, for a list of the file server +machines that house the volume containing the file. The Cache Manager +then requests the file from the File Server running on one of the relevant +file server machines. The file location procedure is invisible to the +user, who only needs to know the file's pathname. + + + +

The VLDB volume entry for a read/write volume also contains the pertinent +information about the read-only and backup versions, which do not have their +own VLDB entries. (The rare exception is a read-only volume that has +its own VLDB entry because its read/write source has been removed.) A +volume's VLDB entry records the volume's name, the unique volume ID +number for each version (read/write, read-only, backup, and releaseClone), a +count of the number of sites that house a read/write or read-only version, and +a list of the sites. +

To display the VLDB entry for one or more volumes, use the vos +listvldb command as described in To display VLDB entries. To display the VLDB entry for a single volume along +with its volume header, use the vos examine command as described in +To display one volume's VLDB entry and volume header. (See the following section for a description of the +volume header.) +

The Information in Volume Headers

+ + +

Whereas all versions of a volume share one VLDB entry, each volume on an +AFS server partition has its own volume header, a data structure +that maps the files and directories in the volume to physical memory addresses +on the partition that stores them. The volume header binds the +volume's contents into a logical unit without requiring that they be +stored in contiguous memory blocks. The volume header also records the +following information about the volume, some of it redundant with the VLDB +entry: name, volume ID number, type, size, status (online, offline, or +busy), space quota, timestamps for creation date and date of last +modification, and number of accesses during the current day. +

To display the volume headers on one or more partitions, use the vos +listvol command as described in To display volume headers. To display the VLDB entry for a single volume along +with its volume header, use the vos examine command as described in +To display one volume's VLDB entry and volume header. +

Keeping the VLDB and Volume Headers Synchronized

+ + + + + + +

It is vital that the information in the VLDB correspond to the status of +the actual volumes on the servers (as recorded in volume headers) as much of +the time as possible. If a volume's location information in the +VLDB is incorrect, the Cache Manager cannot find access its contents. +Whenever you issue a vos command that changes a volume's +status, the Volume Server and VL Server cooperate to keep the volume header +and VLDB synchronized. In rare cases, the header and VLDB can diverge, +for instance because a vos operation halts prematurely. For +instructions on resynchronizing them, see Synchronizing the VLDB and Volume Headers. +

About Mounting Volumes

+ + + +

To make a volume's contents visible in the cell's file tree and +accessible to users, you mount the volume at a directory location in the AFS +filespace. The association between the volume and its location in the +filespace is called a mount point. An AFS mount point looks +and functions like a regular UNIX file system directory, but structurally it +is more like a symbolic link that tells the Cache Manager the name of the +volume associated with the directory. A mount point looks and acts like +a directory only because the Cache Manager knows how to interpret it. +

Consider the common case where the Cache Manager needs to retrieve a file +requested by an application program. The Cache Manager traverses the +file's complete pathname, starting at the AFS root (by convention mounted +at the /afs directory) and continuing to the file. When the +Cache Manager encounters (or crosses) a mount point during the +traversal, it reads it to learn the name of the volume mounted at that +directory location. After obtaining location information about the +volume from the Volume Location (VL) Server, the Cache Manager fetches the +indicated volume and opens its root directory. The root +directory of a volume lists all the files, subdirectories, and mount +points that reside in it. The Cache Manager scans the root directory +listing for the next element in the pathname. It continues down the +path, using this method to interpret any other mount points it encounters, +until it reaches the volume that houses the requested file. + + +

Mount points act as the glue that connects the AFS file space, creating the +illusion of a single, seamless file tree even when volumes reside on many +different file server machines. A volume's contents are visible +and accessible when the volume is mounted at a directory location, and are not +accessible at all if the volume is not mounted. +

You can mount a volume at more than one location in the file tree, but this +is not recommended for two reasons. First, it distorts the hierarchical +nature of the filespace. Second, the Cache Manager can become confused +about which pathname it followed to reach the file (causing unpredictable +output from the pwd command, for example). However, if you +mount a volume at more than one directory, the access control list (ACL) +associated with the volume's root directory applies to all of the mount +points. + + +

There are several types of mount points, each of which the Cache Manager +handles in a different way and each of which is appropriate for a different +purpose. See Mounting Volumes. +

About Volume Names

+ + +

A read/write volume's name can be up to 22 characters in +length. The Volume Server automatically adds the +.readonly and .backup extensions to +read-only and backup volumes respectively. Do not explicitly add the +extensions to volume names, even if they are appropriate. +

It is conventional for a volume's name to indicate the type of data it +houses. For example, it is conventional to name all user volumes +user.username where username is the +user's login name. Similarly, many cells elect to put system +binaries in volumes with names that begin with the system type code. +For a list of other naming conventions, see Creating Volumes to Simplify Administration. + + +

Creating Read/write Volumes

+ + + +

A read/write volume is the most basic type of volume, and must exist before +you can create read-only or backup versions of it. When you issue the +vos create command to create a read/write volume, the VL Server +creates a VLDB entry for it which records the name you specify, assigns a +read/write volume ID number, and reserves the next two consecutive volume ID +numbers for read-only and backup versions that possibly are to be created +later. At the same time, the Volume Server creates a volume header at +the site you designate, allocating space on disk to record the name of the +volume's root directory. The name is filled in when you issue the +fs mkmount command to mount the volume, and matches the mount point +name. The following is also recorded in the volume header: +

An initial ACL associated with the volume's root directory. By +default it grants all seven AFS access permissions to the +system:administrators group. After you mount the +volume, you can use the fs setacl command to add other entries and +to remove or change the entry for the system:administrators +group. See Setting ACL Entries. + + +
A space quota, which limits the amount of disk space the read/write +version of the volume can use on the file server partition. The default +is of 5000 kilobyte blocks, but you can use the -maxquota argument +to the vos create command to set a different quota. +
To change the quota after creation, use the fs setquota command +as described in Setting and Displaying Volume Quota and Current Size. + + +

To create (and mount) a read/write volume

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Verify that you have the a (administer), +i (insert), and l (lookup) +permissions on the ACL of the directory where you plan to mount the +volume. If necessary, issue the fs listacl command, which is +fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. + + +

Select a site (disk partition on a file server machine) for the +new volume. To verify that the site has enough free space to house the +volume (now, or if it grows to use its entire quota), issue the vos +partinfo command. +

Note:

The partition-related statistics in this command's output do not always +agree with the corresponding values in the output of the standard UNIX +df command. The statistics reported by this command can be +up to five minutes old, because the Cache Manager polls the File Server for +partition information at that frequency. Also, on some operating +systems, the df command's report of partition size includes +reserved space not included in this command's calculation, and so is +likely to be about 10% larger. +

   % vos partinfo <machine name> [<partition name>]
+   
+

where +

p +: Is the shortest acceptable abbreviation of partinfo. +
machine name +: Specifies the file server machine for which to display partition size and +usage. +
partition name +: Names one partition for which to display partition size and usage. +If you omit it, the output displays the size and space available for all +partitions on the machine. +

Select a volume name, taking note of the information in About Volume Names. + + +
Issue the vos create command to create the +volume. +
```
   
+   % vos create <machine name> <partition name> <volume name>  \
+                [-maxquota <initial quota (KB)>]
+   
+
```
+
where +
+
cr +
Is the shortest acceptable abbreviation of create. +
machine name +
Specifies the file server machine on which to place the volume. +
partition name +
Specifies the disk partition on which to place the volume. +
volume name +
Names the volume. It can be up to 22 alphanumeric and punctuation +characters in length. Your cell possibly has naming conventions for +volumes, such as beginning user volume names with the string user +and using the period to separate parts of the name. +
-maxquota +
Sets the volume's quota, as a number of kilobyte blocks. If +you omit this argument, the quota is set to 5000 kilobyte blocks. +
+ + + + +
(Optional) Issue the fs mkmount command +to mount the volume in the filespace. For complete syntax, see To create a regular or read/write mount point. +
```
   
+   % fs mkmount <directory> <volume name> 
+   
+
```
+
(Optional) Issue the fs lsmount command to verify +that the mount point refers to the correct volume. Complete +instructions appear in To display a mount point. +
```
   
+   % fs lsmount <directory>
+   
+
```
+
(Optional) Issue the fs setvol command with the +-offlinemsg argument to record auxiliary information about the +volume in its volume header. For example, you can record who owns the +volume or where you have mounted it in the filespace. To display the +information, use the fs examine command. +
```
   % fs setvol <dir/file path> -offlinemsg <offline message>
+
```
+
where +
+
sv +
Is an acceptable alias for setvol (and setv the +shortest acceptable abbreviation). +
dir/file path +
Names the mount point of the volume with which to associate the +message. Partial pathnames are interpreted relative to the current +working directory. +
Specify the read/write path to the mount point, to avoid the failure that +results when you attempt to change a read-only volume. By convention, +you indicate the read/write path 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 Rules of Mount Point Traversal. +
-offlinemsg +
Specifies up to 128 characters of auxiliary information to record in the +volume header. +
+

About Clones and Cloning

+ + + + +

To create a backup or read-only volume, the Volume Server begins by +cloning the read/write source volume to create a +clone. The Volume Server creates the clone automatically +when you issue the vos backup or vos backupsys command +(for a backup volume) or the vos release command (for a read-only +volume). No special action is required on your part. +

A clone is not a copy of the data in the read/write source volume, but +rather a copy of the read/write volume's vnode index. +The vnode index is a table of pointers between the files and directories in +the volume and the physical disk blocks on the partition where the data +resides. From the clone, backup and read-only volumes are created in +the following manner: +

A read-only volume that occupies the same partition as its read/write +source (also known as a read-only clone), and a backup volume, are +created by attaching a volume header to the clone. These volumes +initially consume very little disk space, because the clone portion (the vnode +index) points to exactly the same files as the read/write volume, as +illustrated in Figure 1. The file sharing is possible only because the clone +is on the same partition as the read/write source volume. When a file +in the read/write volume is deleted, it is not actually removed from the +partition, because the backup or read-only clone still points to it. +Similarly, when a file in the read/write is changed, the entire original file +is preserved on disk because the clone still points to it, and the read/write +volume's vnode index changes to point to newly space for the changed +file. When this happens, the backup or read-only volume is said to grow +or start occupying actual disk space. +
A read-only volume that does not occupy the same site as the read/write +source is a copy of the clone and of all of the data in the read/write source +volume. It occupies the same amount of disk space as the read/write +volume did at the time the read-only volume was created. +

Figure 1. File Sharing Between the Read/write Source and a Clone Volume
+

+

+
+ + + + + + + +

Replicating Volumes (Creating Read-only Volumes)

Replication refers to creating a read-only copy +of a read/write volume and distributing the copy to one or more additional +file server machines. Replication makes a volume's contents +accessible on more than one file server machine, which increases data +availability. It can also increase system efficiency by reducing load +on the network and File Server. Network load is reduced if a client +machine's server preference ranks lead the Cache Manager to access the +copy of a volume stored on the closest file server machine. Load on the +File Server is reduced because it issues only one callback for all data +fetched from a read-only volume, as opposed to a callback for each file +fetched from a read/write volume. The single callback is sufficient for +an entire read-only volume because the volume does not change except in +response to administrator action, whereas each read/write file can change at +any time. + + + + + +

Replicating a volume requires issuing two commands. First, use the +vos addsite command to add one or more read-only site definitions +to the volume's VLDB entry (a site is a particular partition +on a file server machine). Then use the vos release command +to clone the read/write source volume and distribute the clone to the defined +read-only sites. You issue the vos addsite only once for +each read-only site, but must reissue the vos release command every +time the read/write volume's contents change and you want to update the +read-only volumes. +

For users to have a consistent view of the file system, the release of +updated volume contents to read-only sites must be atomic: either all +read-only sites receive the new version of the volume, or all sites keep the +version they currently have. The vos release command is +designed to ensure that all copies of the volume's read-only version +match both the read/write source and each other. In cases where +problems such as machine or server process outages prevent successful +completion of the release operation, AFS uses two mechanisms to alert +you. + + + + + + + + + + + + + + +

First, the command interpreter generates an error message on the standard +error stream naming each read-only site that did not receive the new volume +version. Second, during the release operation the Volume Location (VL) +Server marks site definitions in the VLDB entry with flags (New +release and Old release) that indicate whether or not the +site has the new volume version. If any flags remain after the +operation completes, it was not successful. The Cache Manager refuses +to access a read-only site marked with the Old release flag, which +potentially imposes a greater load on the sites marked with the New +release flag. It is important to investigate and eliminate the +cause of the failure and then to issue the vos release command as +many times as necessary to complete the release without errors. +

The pattern of site flags remaining in the volume's VLDB entry after a +failed release operation can help determine the point at which the operation +failed. Use the vos examine or vos listvldb +command to display the VLDB entry. The VL Server sets the flags in +concert with the Volume Server's operations, as follows: +

Before the operation begins, the VL Server sets the New release +flag on the read/write site definition in the VLDB entry and the Old +release flag on read-only site definitions (unless the read-only site +has been defined since the last release operation and has no actual volume, in +which case its site flag remains Not released). +
If necessary, the Volume Server creates a temporary copy (a +clone) of the read/write source called the ReleaseClone (see the +following discussion of when the Volume Server does or does not create a new +ReleaseClone.) It assigns the ReleaseClone its own volume ID number, +which the VL Server records in the RClone field of the source +volume's VLDB entry. +
The Volume Server distributes a copy of the ReleaseClone to each read-only +site defined in the VLDB entry. As the site successfully receives the +new clone, the VL Server sets the site's flag in the VLDB entry to +New release. +
When all the read-only copies are successfully released, the VL Server +clears all the New release site flags. The ReleaseClone is +no longer needed, so the Volume Server deletes it and the VL Server erases its +ID from the VLDB entry. +

By default, the Volume Server determines automatically whether or not it +needs to create a new ReleaseClone: +

If there are no flags (New release, Old release, or +Not released) on site definitions in the VLDB entry, the previous +vos release command completed successfully and all read-only sites +currently have the same volume. The Volume Server infers that the +current vos release command was issued because the read/write +volume has changed. The Volume Server creates a new ReleaseClone and +distributes it to all of the read-only sites. +
If any site definition in the VLDB entry is marked with a flag, either the +previous release operation did not complete successfully or a new read-only +site was defined since the last release. The Volume Server does not +create a new ReleaseClone, instead distributing the existing ReleaseClone to +sites marked with the Old release or Not released +flag. As previously noted, the VL Server marks each VLDB site +definition with the New release flag as the site receives the +ReleaseClone, and clears all flags after all sites successfully receive +it. +

To override the default behavior, forcing the Volume Server to create and +release a new ReleaseClone to the read-only sites, include the -f +flag. This is appropriate if, for example, the data at the read/write +site has changed since the existing ReleaseClone was created during the +previous release operation. +

Using Read-only Volumes Effectively

+ + + + +

For maximum effectiveness, replicate only volumes that satisfy two +criteria: +

The volume's contents are heavily used. Examples include a +volume housing binary files for text editors or other popular application +programs, and volumes mounted along heavily traversed directory paths such as +the paths leading to user home directories. It is an inefficient use of +disk space to replicate volumes for which the demand is low enough that a +single File Server can easily service all requests. +
The volume's contents change infrequently. As noted, file +system consistency demands that the contents of read-only volumes must match +each other and their read/write source at all times. Each time the +read/write volume changes, you must issue the vos release command +to update the read-only volumes. This can become tedious (and easy to +forget) if the read/write volume changes frequently. +

+ + +

Explicitly mounting a read-only volume (creating a mount point that names a +volume with a .readonly extension) is not generally +necessary or appropriate. The Cache Manager has a built-in bias to +access the read-only version of a replicated volume whenever possible. +As described in more detail in The Rules of Mount Point Traversal, when the Cache Manager encounters a mount point it reads +the volume name inside it and contacts the VL Server for a list of the sites +that house the volume. In the normal case, if the mount point resides +in a read-only volume and names a read/write volume (one that does not have a +.readonly or .backup extension), the Cache +Manager always attempts to access a read-only copy of the volume. Thus +there is normally no reason to force the Cache Manager to access a read-only +volume by mounting it explicitly. +

It is a good practice to place a read-only volume at the read/write site, +for a couple of reasons. First, the read-only volume at the read/write +site requires only a small amount of disk space, because it is a clone rather +a copy of all of the data (see About Clones and Cloning). Only if a large number of files are removed or +changed in the read/write volume does the read-only copy occupy much disk +space. That normally does not happen because the appropriate response +to changes in a replicated read/write volume is to reclone it. The +other reason to place a read-only volume at the read/write site is that the +Cache Manager does not attempt to access the read/write version of a +replicated volume if all read-only copies become inaccessible. If the +file server machine housing the read/write volume is the only accessible +machine, the Cache Manager can access the data only if there is a read-only +copy at the read/write site. +

The number of read-only sites to define depends on several factors. +Perhaps the main trade-off is between the level of demand for the +volume's contents and how much disk space you are willing to use for +multiple copies of the volume. Of course, each prospective read-only +site must have enough available space to accommodate the volume. The +limit on the number of read-only copies of a volume is determined by the +maximum number of site definitions in a volume's VLDB entry, which is +defined in the IBM AFS Release Notes. The site housing the +read/write and backup versions of the volume counts as one site, and each +read-only site counts as an additional site (even the read-only site defined +on the same file server machine and partition as the read/write site counts as +a separate site). Note also that the Volume Server permits only one +read-only copy of a volume per file server machine. +

Replication Scenarios

+ + + +

The instructions in the following section explain how to replicate a volume +for which no read-only sites are currently defined. However, you can +also use the instructions in other common situations: +

If you are releasing a new clone to sites that already exist, you can skip +Step 2. It can still be useful to issue the vos +examine command, however, to verify that the desired read-only sites are +defined. +
If you are adding new read-only sites to existing ones, perform all of the +steps. In Step 3, issue the vos addsite command for the new sites +only. +
If you are defining sites but do not want to release a clone to them yet, +stop after Step 3 and continue when you are ready. +
If you are removing one or more sites before releasing a new clone to the +remaining sites, follow the instructions for site removal in Removing Volumes and their Mount Points and then start with Step 4. +

To replicate a read/write volume (create a read-only volume)

+ + +

Verify that you are listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Select one or more sites at which to replicate the +volume. There are several factors to consider: +
- How many sites are already defined. As previously noted, it is +usually appropriate to define a read-only site at the read/write site. +Also, the Volume Server permits only one read-only copy of a volume per file +server machine. To display the volume's current sites, issue the +vos examine command, which is described fully in Displaying One Volume's VLDB Entry and Volume Header. +
```
   
+   % vos examine <volume name or  ID>
+    
+
```
  +
  The final lines of output display the volume's site definitions from +the VLDB. +
- Whether your cell dedicates any file server machines to housing read-only +volumes only. In general, only very large cells use read-only server +machines. +
- Whether a site has enough free space to accommodate the volume. A +read-only volume requires the same amount of space as the read/write version +(unless it is at the read/write site itself). The first line of output +from the vos examine command displays the read/write volume's +current size in kilobyte blocks, as shown in Displaying One Volume's VLDB Entry and Volume Header. +
  To display the amount of space available on a file server machine's +partitions, use the vos partinfo command, which is described fully +in Creating Read/write Volumes. +
```
   
+   % vos partinfo <machine name> [<partition name>]
+   
+
```
  +
+ + + + + + +
Issue the vos addsite command to define each new +read-only site in the VLDB. +
```
   
+   % vos addsite <machine name> <partition name> <volume name or ID>
+   
+
```
+
where +
+
ad +
Is the shortest acceptable abbreviation of addsite. +
machine name +
Defines the file server machine for the new site. +
partition name +
Names a disk partition on the machine machine name. +
volume name or ID +
Identifies the read/write volume to be replicated, either by its complete +name or its volume ID number. +
+
(Optional) Verify that the fs process +(which incorporates the Volume Server) is functioning normally on each file +server machine where you have defined a read-only site, and that the +vlserver process (the Volume Location Server) is functioning +correctly on each database server machine. Knowing that they are +functioning eliminates two possible sources of failure for the release. +Issue the bos status command on each file server machine housing a +read-only site for this volume and on each database server machine. The +command is described fully in Displaying Process Status and Information from the BosConfig File. +
```
   
+   % bos status <machine name> fs vlserver
+   
+
```
+ + + + +
Issue the vos release command to clone the +read/write source volume and distribute the clone to each read-only +site. +
```
   
+   % vos release <volume name or ID> [-f]
+   
+
```
+
where +
+
rel +
Is the shortest acceptable abbreviation of release. +
volume name or ID +
Identifies the read/write volume to clone, either by its complete name or +volume ID number. The read-only version is given the same name with a +.readonly extension. All read-only copies share the +same read-only volume ID number. +
-f +
Creates and releases a brand new clone. +
+
(Optional) Issue the vos examine command +to verify that no site definition in the VLDB entry is marked with an Old +release or New release flag. The command is described +fully in Displaying One Volume's VLDB Entry and Volume Header. +
```
   
+   % vos examine <volume name or ID>
+   
+
```
+

If any flags appear in the output from Step 6, repeat Steps 4 and 5 until the Volume Server +does not produce any error messages during the release operation and the flags +no longer appear. Do not issue the vos release command when +you know that the read/write site or any read-only site is inaccessible due to +network, machine or server process outage. +

Creating Backup Volumes

+ + + + + +

A backup volume is a clone that resides at the same site as its +read/write source (to review the concept of cloning, see About Clones and Cloning). Creating a backup version of a volume has two +purposes: +

It is by convention the first step when dumping a volume's contents +to tape with the AFS Backup System. A volume is inaccessible while it +is being dumped, so instead of dumping the read/write volume, you create and +dump a backup version. Users do not normally access the backup version, +so it is unlikely that the dump will disturb them. For more details, +see Backing Up Data. +
It enables users to restore mistakenly deleted or changed data themselves, +freeing you for more crucial tasks. The backup version captures the +state of its read/write source at the time the backup is made, and its +contents cannot change. Mount the backup version in the filespace so +that users can restore a file to its state at the time you made the +backup. See Making the Contents of Backup Volumes Available to Users. +

+ + + +

Backing Up Multiple Volumes at Once

The vos backupsys command creates a backup +version of many read/write volumes at once. This command is useful when +preparing for large-scale backups to tape using the AFS Backup System. +

To clone every read/write volume listed in the VLDB, omit all of the +command's options. Otherwise, combine the command's options +to clone various groups of volumes. The options use one of two basic +criteria to select volumes: location (the -server and +-partition arguments) or presence in the volume name of one of a +set of specified character strings (the -prefix, +-exclude, and -xprefix options). +

To clone only volumes that reside on one file server machine, include the +-server argument. To clone only volumes that reside on one +partition, combine the -server and -partition +arguments. The -partition argument can also be used alone to +clone volumes that reside on the indicated partition on every file server +machine. These arguments can be combined with those that select volumes +based on their names. +

Combine the -prefix, -exclude, and +-xprefix options (with or without the -server and +-partition arguments) in the indicated ways to select volumes based +on character strings contained in their names: +

To clone every read/write volume at the specified location whose name +includes one of a set of specified character strings (for example, begins with +user. or includes the string afs), use the +-prefix argument or combine the -xprefix and +-exclude options. +
To clone every read/write volume at the specified location except those +whose name includes one of a set of specified character strings, use the +-xprefix argument or combine the -prefix and +-exclude options. +
To clone every read/write volume at the specified location whose name +includes one of one of a set of specified character strings, except those +whose names include one of a different set of specified character strings, +combine the -prefix and -xprefix arguments. The +command creates a list of all volumes that match the -prefix +argument and then removes from the list the volumes that match the +-xprefix argument. For effective results, the strings +specified by the -xprefix argument must designate a subset of the +volumes specified by the -prefix argument. +
If the -exclude flag is combined with the -prefix and +-xprefix arguments, the command creates a list of all volumes that +do not match the -prefix argument and then adds to the list any +volumes that match the -xprefix argument. As when the +-exclude flag is not used, the result is effective only if the +strings specified by the -xprefix argument designate a subset of +the volumes specified by the -prefix argument. +

The -prefix and -xprefix arguments both accept +multiple values, which can be used to define disjoint groups of +volumes. Each value can be one of two types: +

A simple character string, which matches volumes whose name begin with the +string. All characters are interpreted literally (that is, characters +that potentially have special meaning to the command shell, such as the +period, have only their literal meaning). +
A regular expression, which matches volumes whose names contain the +expressions. Place a caret ( ^ ) at the +beginning of the expression, and enclose the entire string in single quotes +(' '). Explaining regular +expressions is outside the scope of this reference page; see the UNIX +manual page for regexp(5) or (for a brief introduction) Defining and Displaying Volume Sets and Volume Entries. As an example, the following expression matches +volumes that have the string aix anywhere in their names: +
```
   -prefix  '^.*aix'
+
```
+

To display a list of the volumes to be cloned, without actually cloning +them, include the -dryrun flag. To display a statement that +summarizes the criteria being used to select volume, include the +-verbose flag. +

To back up a single volume, use the vos backup command, which +employs a more streamlined technique for finding a single volume. + + + + + + +

Automating Creation of Backup Volumes

Most cells find that it is best to make a new backup version +of relevant volumes each day. It is best to create the backup versions +at a time when usage is low, because the backup operation causes the +read/write volume to be unavailable momentarily. +

You can either issue the necessary the vos backupsys or vos +backup commands at the console or create a cron entry in the +BosConfig file on a file server machine, which eliminates the need +for an administrator to initiate the backup operation. +

The following example command creates a cron process called +backupusers in the /usr/afs/local/BosConfig file on the +machine fs3.abc.com. The process runs every +day at 1:00 a.m. to create a backup version of every +volume in the cell whose name starts with the string user. +The -localauth flag enables the process to invoke the privileged +vos backupsys command while unauthenticated. Note that the +-cmd argument specifies a complete pathname for the vos +binary, because the PATH environment variable for the BOS Server (running as +the local superuser root) generally does not include the path to +AFS binaries. +

   
+   % bos create fs3.abc.com backupusers cron  \
+     -cmd "/usr/afs/bin/vos backupsys  -prefix user -localauth" "1:00"
+    
+

+ + + +

Making the Contents of Backup Volumes Available to Users

As noted, a backup volume preserves the state of the +read/write source at the time the backup is created. Many cells choose +to mount backup volumes so that users can access and restore data they have +accidentally deleted or changed since the last backup was made, without having +to request help from administrators. The most sensible place to mount +the backup version of a user volume is at a subdirectory of the user's +home directory. Suitable names for this directory include +OldFiles and Backup. The subdirectory looks just +like the user's own home directory as it was at the time the backup was +created, with all files and subdirectories in the same relative +positions. +

If you do create and mount backup volumes for your users, inform users of +their existence. The IBM AFS User Guide does not mention +backup volumes because making them available to users is optional. +Explain to users how often you make a new backup, so they know what they can +recover. Remind them also that the data in their backup volume cannot +change; however, they can use the standard UNIX cp command to +copy it into their home volume and modify it there. Reassure users that +the data in their backup volumes does not count against their read/write +volume quota. +

To create and mount a backup volume

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Verify that you have the insert (i) and +administer (a) permissions on the ACL of the directory +in which you wish to mount the volume. If necessary, issue the fs +listacl command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. + + +
Issue the vos backup command to create a backup +version of a read/write source volume. The message shown confirms the +success of the backup operation. +
```
   
+   % vos backup <volume name or ID>
+   Created backup volume for volume name or ID
+   
+
```
+
where +
+
backup +
Must be typed in full. +
volume name or ID +
Identifies the read/write volume to back up, either by its complete name +or volume ID number. The backup volume has the same name with the +addition of the .backup extension. It has its own +volume ID number. +
+ + +
(Optional) Issue the fs mkmount to mount +the backup volume. While this step is optional, Cache Managers cannot +access the volume's contents if it is not mounted. +
```
   
+   % fs mkmount <directory> <volume name>.backup
+   
+
```
+
where +
+
mk +
Is the shortest acceptable abbreviation of mkmount. +
directory +
Names the mount point to create. Do not create a file or directory +of the same name beforehand. Partial pathnames are interpreted relative +to the current working directory. For the backup version of a user +volume, the conventional location is the user's home directory. +
volume name.backup +
Is the full name of the backup volume. +
+
(Optional) Issue the fs lsmount command to verify +that the mount point refers to the correct volume. Complete +instructions appear in To display a mount point. +
```
   
+   % fs lsmount <directory>
+   
+
```
+

+ + +

To create multiple backup volumes at once

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the vos backupsys command to create a backup version of +every read/write volume that shares the same prefix or site. The +effects of combining the three arguments are described in Backing Up Multiple Volumes at Once. +
```
   % vos backupsys [-prefix <common prefix on volume(s)>⁺]   \
+        [-server <machine name>] [-partition <partition name>]  \
+        [-exclude]   [-xprefix <negative prefix on volume(s)>⁺] 
+        [-dryrun]  [-verbose]
+   
+
```
+
where +
+
backups +
Is the shortest acceptable abbreviation of backupsys. +
-prefix +
Specifies one or more simple character strings or regular expressions of +any length; a volume whose name includes the string is placed on the list +of volumes to be cloned. Include field separators (such as periods) if +appropriate. This argument can be combined with any combination of the +-server, -partition, -exclude, and +-xprefix options. +
-server +
Specifies the file server machine housing the volumes to backup. +Can be combined with any combination of the -prefix, +-partition, -exclude, and -xprefix +options. +
-partition +
Specifies the partition housing the volumes you wish to backup. Can +be combined with any combination of the -prefix, +-server, -exclude, and -xprefix +options. +
-exclude +
Indicates that all volumes except those indicated with the +-prefix argument are to be backed up. The -prefix +argument must be provided along with this one. Can also be combined +with any combination of the -prefix, -server, and +-partition arguments; or with both the -prefix and +-xprefix arguments, but not with the -xprefix argument +alone. +
-xprefix +
Specifies one or more simple character strings or regular expressions of +any length; a volume whose name does not include the string is placed on +the list of volumes to be cloned. Can be combined with any combination +of the -prefix, -server, and -partition +arguments; in addition, it can be combined with both the +-prefix and -exclude options, but not with the +-exclude flag alone. +
-dryrun +
Displays on the standard output stream a list of the volumes to be cloned, +without actually cloning them. +
-verbose +
Displays on the standard output stream a statement that summarizes the +criteria being used to select volumes, if combined with the -dryrun +flag; otherwise, traces the cloning operation for each volume. +
+

Mounting Volumes

+ +

Mount points make the contents of AFS volumes visible and accessible in the +AFS filespace, as described in About Mounting Volumes. This section discusses in more detail how the Cache +Manager handles mount points as it traverses the filespace. It +describes the three types of mount points, their purposes, and how to +distinguish between them, and provides instructions for creating, removing, +and examining mount points. +

The Rules of Mount Point Traversal

The Cache Manager observes three basic rules as it traverses +the AFS filespace and encounters mount points: +

Rule 1: Access Backup and Read-only Volumes When +Specified +
When the Cache Manager encounters a mount point that specifies a volume +with either a .readonly or a .backup +extension, it accesses that type of volume only. If a mount point does +not have either a .backup or .readonly +extension, the Cache Manager uses Rules 2 and 3. +
For example, the Cache Manager never accesses the read/write version of a +volume if the mount point names the backup version. If the specified +version is inaccessible, the Cache Manager reports an error. +
Rule 2: Follow the Read-only Path When Possible +
If a mount point resides in a read-only volume and the volume that it +references is replicated, the Cache Manager attempts to access a read-only +copy of the volume; if the referenced volume is not replicated, the Cache +Manager accesses the read/write copy. The Cache Manager is thus said to +prefer a read-only path through the filespace, accessing read-only +volumes when they are available. +
The Cache Manager starts on the read-only path in the first place because +it always accesses a read-only copy of the root.afs volume +if it exists; the volume is mounted at the root of a cell's AFS +filespace (named /afs by convention). That is, if the +root.afs volume is replicated, the Cache Manager attempts to +access a read-only copy of it rather than the read/write copy. This +rule then keeps the Cache Manager on a read-only path as long as each +successive volume is replicated. The implication is that both the +root.afs and root.cell volumes must be +replicated for the Cache Manager to access replicated volumes mounted below +them in the AFS filespace. The volumes are conventionally mounted at +the /afs and /afs/cellname directories, +respectively. +
Rule 3: Once on a Read/write Path, Stay There +
If a mount point resides in a read/write volume and the volume name does +not have a .readonly or a .backup +extension, the Cache Manager attempts to access only the a read/write version +of the volume. The access attempt fails with an error if the read/write +version is inaccessible, even if a read-only version is accessible. In +this situation the Cache Manager is said to be on a read/write path +and cannot switch back to the read-only path unless mount point explicitly +names a volume with a .readonly extension. (Cellular +mount points are an important exception to this rule, as explained in the +following discussion. +

The Three Types of Mount Points

AFS uses three types of mount points, each appropriate for a +different purpose because of how the Cache Manager handles them. +

When the Cache Manager crosses a regular mount point, it obeys +all three of the mount point traversal rules previously described. + + +

AFS performs best when the vast majority of mount points in the filespace +are regular, because the mount point traversal rules promote the most +efficient use of both replicated and nonreplicated volumes. Because +there are likely to be multiple read-only copies of a replicated volume, it +makes sense for the Cache Manager to access one of them rather than the single +read/write version, and the second rule leads it to do so. If a volume +is not replicated, the third rule means that the Cache Manager still accesses +the read/write volume when that is the only type available. In other +words, a regular mount point does not force the Cache Manager always to access +read-only volumes (it is explicitly not a "read-only mount point"). +

To create a regular mount point, use the fs mkmount command as +described in To create a regular or read/write mount point. +
Note: To enable the Cache Manager to access the read-only version of a replicated +volume named by a regular mount point, all volumes that are mounted above it +in the pathname must also be replicated. That is the only way the Cache +Manager can stay on a read-only path to the target volume. +
+

When the Cache Manager crosses a read/write mount point, it +attempts to access only the volume version named in the mount point. If +the volume name is the base (read/write) form, without a +.readonly or .backup extension, the Cache +Manager accesses the read/write version of the volume, even if it is +replicated. In other words, the Cache Manager disregards the second +mount point traversal rule when crossing a read/write mount point: it +switches to the read/write path through the filespace. + + +
It is conventional to create only one read/write mount point in a +cell's filespace, using it to mount the cell's +root.cell volume just below the AFS filespace root (by +convention, /afs/.cellname). As indicated, +it is conventional to place a period at the start of the read/write mount +point's name (for example, +/afs/.abc.com). The period distinguishes the +read/write mount point from the regular mount point for the +root.cell volume at the same level. This is the only +case in which it is conventional to create two mount points for the same +volume. A desirable side effect of this naming convention for this +read/write mount point is that it does not appear in the output of the UNIX +ls command unless the -a flag is included, essentially +hiding it from regular users who have no use for it. +
The existence of a single read/write mount point at this point in the +filespace provides access to the read/write version of every volume when +necessary, because it puts the Cache Manager on a read/write path right at the +top of the filespace. At the same time, the regular mount point for the +root.cell volume puts the Cache Manager on a read-only path +most of the time. +
Using a read/write mount point for a read-only or backup volume is +acceptable, but unnecessary. The first rule of mount point traversal +already specifies that the Cache Manager accesses them if the volume name in a +regular mount point has a .readonly or +.backup extension. +
To create a read/write mount point, use the -rw flag on the +fs mkmount command as described in To create a regular or read/write mount point. +
When the Cache Manager crosses a cellular mount point, it +accesses the indicated volume in the specified cell, which is normally a +foreign cell. (If the mount point does not name a cell along with the +volume, the Cache Manager accesses the volume in the cell where the mount +point resides.) When crossing a regular cellular mount point, the Cache +Manager disregards the third mount point traversal rule. Instead, it +accesses a read-only version of the volume if it is replicated, even if the +volume that houses the mount point is read/write. +
It is inappropriate to circumvent this behavior by creating a read/write +cellular mount point, because traversing the read/write path imposes an unfair +load on the foreign cell's file server machines. The File Server +must issue a callback for each file fetched from the read/write volume, rather +than single callback required for a read-only volume. In any case, only +a cell's own administrators generally need to access the read/write +versions of replicated volumes. + + + +
It is conventional to create cellular mount points only at the second level +in a cell's filespace, using them to mount foreign cells' +root.cell volumes just below the AFS filespace root (by +convention, at /afs/foreign_cellname). The mount +point enables local users to access the foreign cell's filespace, +assuming they have the necessary permissions on the ACL of the volume's +root directory and that there is an entry for the foreign cell in each local +client machine's /usr/vice/etc/CellServDB file, as described +in Maintaining Knowledge of Database Server Machines. +
Creating cellular mount points at other levels in the filespace and +mounting foreign volumes other than the root.cell volume is +not generally appropriate. It can be confusing to users if the Cache +Manager switches between cells at various points in a pathname. +
To create a regular cellular mount point, use the -cell argument +to specify the cell name, as described in To create a cellular mount point. +

To examine a mount point, use the fs lsmount command as +described in To display a mount point. The command's output uses distinct notation to +identify regular, read/write, and cellular mount points. To remove a +mount point, use the fs rmmount command as described in To remove a mount point. +

Creating a mount point in a foreign cell

Creating a mount point in a foreign cell's filespace (as opposed +to mounting a foreign volume in the local cell) is basically the same as +creating a mount point in the local filespace. The differences are that +the fs mkmount command's directory argument specifies +a pathname in the foreign cell rather than the local cell, and you must have +the required permissions on the ACL of the foreign directory where you are +creating the mount point. The fs mkmount command's +-cell argument always specifies the cell in which the volume +resides, not the cell in which to create the mount point. +

To display a mount point

+ + + + + + +

Issue the fs lsmount command. +
```
   
+   % fs lsmount <directory>
+   
+
```
+
where +
+
ls +
Is the shortest acceptable abbreviation of lsmount. +
directory +
Names the mount point to display. +
+

If the specified directory is a mount point, the output is of the following +form: +

   'directory' is a mount point for volume 'volume name'
+   
+

For a regular mount point, a number sign (#) precedes the +volume name string, as in the following example command issued on a +client machine in the abc.com cell. +

   
+   % fs lsmount /afs/abc.com/usr/terry
+   '/afs/abc.com/usr/terry' is a mount point for volume '#user.terry'
+      
+

For a read/write mount point, a percent sign (%) precedes the +volume name string, as in the following example command issued on a +client machine in the abc.com cell. The cell's +administrators have followed the convention of preceding the read/write mount +point's name with a period. +

   
+   % fs lsmount /afs/.abc.com 
+   '/afs/.abc.com' is a mount point for volume '%root.cell'
+   
+

For a cellular mount point, a cell name and colon (:) +follow the number or percent sign and precede the volume name string, +as in the following example command issued on a client machine in the +abc.com cell. +

   
+    % fs lsmount /afs/ghi.gov 
+   '/afs/ghi.gov' is a mount point for volume '#ghi.gov:root.cell'
+   
+

For a symbolic link to a mount point, the output is of the form shown in +the following example command issued on a client machine in the +abc.com cell. +

   
+   % fs lsmount /afs/abc
+   '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
+   
+

If the directory is not a mount point or is not in AFS, the output reads as +follows. +

   'directory' is not a mount point.
+   
+

If the output is garbled, it is possible that the mount point has become +corrupted in the local cache. Use the fs flushmount command +as described in To flush one or more mount points. This forces the Cache Manager to refetch the mount +point. +

To create a regular or read/write mount point

+ + + + + + +

Verify that you have the i (insert) and a +(administer) permissions on the ACL of the directory where you are +placing the mount point. If necessary, issue the fs listacl +command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Issue the fs mkmount command to create the mount point. +Include the -rw flag if creating a read/write mount point. +
```
   
+   % fs mkmount <directory> <volume name>  [-rw]
+   
+
```
+
where +
+
mk +
Is the shortest acceptable abbreviation for mkmount. +
directory +
Names the mount point to create. A file or directory with the same +name cannot already exist. A partial pathname is interpreted relative +to the current working directory. +
Specify the read/write path to the mount point, to avoid the failure that +results when you attempt to create a new mount point in a read-only +volume. By convention, you indicate the read/write path 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 Rules of Mount Point Traversal. +
volume name +
Specifies the volume's full name, including the +.backup or .readonly extension for a +backup or read-only volume, if appropriate. +
-rw +
Creates a read/write mount point. +
+

To create a cellular mount point

+ + + +

Verify that you have the i (insert) and a +(administer) permissions on the ACL of the directory where you are +placing the mount point. If necessary, issue the fs listacl +command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
If you are mounting one or more foreign cells' +root.cell volume at the second level in your filespace and +your cell's root.afs volume is replicated, you must +create a temporary mount point for the root.afs +volume's read/write version in a directory on which the ACL grants you +the i and a permissions. The following command +creates a mount point called new_cells in your cell's +/afs/.cellname directory (the entry point to the +read/write path in your cell). +
Substitute your cell's name for cellname. +
```
   
+   % cd /afs/.cellname
+   
+   % fs  mkmount  new_cells  root.afs
+ 
+   % cd  new_cells
+   
+
```
+
Issue the fs mkmount command with the -cell argument +to create a cellular mount point. Repeat the command for each cellular +mount point as required. +
```
   
+   % fs mkmount <directory> <volume name> -cell <cell name>
+   
+
```
+
where +
+
mk +
Is the shortest acceptable abbreviation for mkmount. +
directory +
Names the mount point to create. A file or directory with the same +name cannot already exist. A partial pathname is interpreted relative +to the current working directory. If you are mounting a foreign +cell's root.cell volume, the standard value for this +argument is the cell's complete Internet domain name. +
volume name +
Specifies the volume's full name, usually root.cell +for a cellular mount point. +
-cell +
Specifies the complete Internet domain name of the cell in which the +volume resides. +
+
If you performed the instructions in Step 2, issue the vos release command to release the new +version of the root.afs volume to its read-only +sites. (This command requires that you be listed in your cell's +/usr/afs/etc/UserList file. If necessary, verify by issuing +the bos listusers command, which is fully described in To display the users in the UserList file.) +
Also issue the fs checkvolumes command to force the local Cache +Manager to access the new replica of the root.afs +volume. If desired, you can also remove the temporary +new_cells mount point from the +/afs/.cellname directory. +
```
     
+   % vos release root.afs
+   
+   %  fs checkvolumes
+   
+   % cd /afs/.cellname
+    
+   % fs rmmount new_cells
+   
+   
+
```
+
For your users to access a newly mounted foreign cell, you must also create +an entry for it in each client machine's local +/usr/vice/etc/CellServDB file and either reboot the machine or use +the fs newcell command to insert the entry directly into its kernel +memory. See the instructions in Maintaining Knowledge of Database Server Machines. +

To remove a mount point

+ + + + + +

Verify that you have the d (delete) permission on +the ACL of the directory from which you are removing the mount point. +If necessary, issue the fs listacl command, which is fully +described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
Issue the fs rmmount command to remove the mount point. +The volume still exists, but its contents are inaccessible if this is the only +mount point for it. +
```
   
+   % fs rmmount <directory>
+   
+
```
+
where +
+
rm +
Is the shortest acceptable abbreviation of rmmount. +
directory +
Names the mount point to remove. A partial pathname is interpreted +relative to the current working directory. +
Specify the read/write path to the mount point, to avoid the failure that +results when you attempt to delete a mount point from a read-only +volume. By convention, you indicate the read/write path 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 Rules of Mount Point Traversal. +
+

Displaying Information About Volumes

+ + +

This section explains how to display information about volumes. If +you know a volume's name or volume ID number, there are commands for +displaying its VLDB entry, its volume header, or both. Other commands +display the name or location of the volume that contains a specified file or +directory. +

For instructions on displaying a volume's quota, see Setting and Displaying Volume Quota and Current Size. +

Displaying VLDB Entries

+ + + + +

The vos listvldb command displays the VLDB entry for the volumes +indicated by the combination of arguments you provide. The +possibilities are listed here from most to least inclusive: +

To display every entry in the VLDB, provide no arguments. It can +take a long time to generate the output, depending on the number of +entries. +
To display every VLDB entry that mentions a specific file server machine +as the site of a volume, specify the machine's name with the +-server argument. +
To display every VLDB entry that mentions a certain partition on any file +server machine as the site of a volume, specify the partition name with the +-partition argument. +
To display every VLDB entry that mentions a certain partition on a certain +file server machine as the site of a volume, combine the -server +and -partition arguments. +
To display a single VLDB entry, specify a volume name or ID number with +the -name argument. +
To display the VLDB entry only for volumes with locked VLDB entries, use +the -locked flag with any of the site definitions mentioned +previously. +

+ + +

To display VLDB entries

Issue the vos listvldb command. +
```
   
+   % vos listvldb  [-name <volume name or ID>] [-server <machine name>] \
+                  [-partition <partition name>] [-locked]
+   
+
```
+
where +
+
listvl +
Is the shortest acceptable abbreviation of listvldb. +
-name +
Identifies one volume either by its complete name or volume ID +number. Do not combine this argument with the -server or +-partition arguments. +
-server +
Specifies a file server machine. Combine this argument with the +-partition argument if desired, but not with the -name +argument. +
-partition +
Specifies a partition. Combine this argument with the +-server argument if desired, but not with the -name +argument. +
-locked +
Displays only locked VLDB entries. Combine this flag with any of +the other options. +
+

The VLDB entry for each volume includes the following information: +

The base (read/write) volume name. The read-only and backup +versions have the same name with a .readonly and +.backup extension, respectively. +
The volume ID numbers allocated to the versions of the volume that +actually exist, in fields labeled RWrite for the read/write, +ROnly for the read-only, Backup for the backup, and +RClone for the ReleaseClone. (If a field does not appear, +the corresponding version of the volume does not exist.) The appearance +of the RClone field normally indicates that a release operation did +not complete successfully; the Old release and New +release flags often also appear on one or more of the site definition +lines described just following. + + +
The number of sites that house a read/write or read-only copy of the +volume, following the string number of sites ->. + + + + + +
A line for each site that houses a read/write or read-only copy of the +volume, specifying the file server machine, partition, and type of volume +(RW for read/write or RO for read-only). If a +backup version exists, it is understood to share the read/write site. +Several flags can appear with a site definition: +
+ +
Not released +
Indicates that the vos release command has not been issued +since the vos addsite command was used to define the read-only +site. + +
Old release +
Indicates that a vos release command did not complete +successfully, leaving the previous, obsolete version of the volume at this +site. + +
New release +
Indicates that a vos release command did not complete +successfully, but that this site did receive the correct new version of the +volume. +
+
If the VLDB entry is locked, the string Volume is currently +LOCKED. +

For further discussion of the New release and Old +release flags, see Replicating Volumes (Creating Read-only Volumes). +

An example of this command and its output for a single volume: +

   
+   % vos listvldb user.terry
+   user.terry
+       RWrite: 50489902    Backup: 50489904
+       number of sites -> 1
+          server fs3.abc.com partition /vicepc RW Site
+  
+

Displaying Volume Headers

+ + +

The vos listvol command displays the volume header for every +volume on one or all partitions on a file server machine. The +vos command interpreter obtains the information from the Volume +Server on the specified machine. You can control the amount of +information displayed by including one of the -fast, the +-long, or the -extended flags described following the +instructions in To display volume headers. +

To display a single volume's volume header of one volume only, use the +vos examine command as described in Displaying One Volume's VLDB Entry and Volume Header. + + +

To display volume headers

Issue the vos listvol command. +
```
   
+   % vos listvol <machine name> [<partition name>] [-fast] [-long] [-extended]
+   
+
```
+
where +
+
listvo +
Is the shortest acceptable abbreviation of listvol. +
machine name +
Names the file server machine for which to display volume headers. +Provide this argument alone or with the partition name +argument. +
partition name +
Names one partition on the file server machine named by the machine +name argument, which must be provided along with this one. +
-fast +
Displays only the volume ID numbers of relevant volumes. Do not +combine this flag with the -long or -extended +flag. +
-long +
Displays more detailed information about each volume. Do not +combine this flag with the -fast or -extended +flag. +
-extended +
Displays all of the information displayed by the -long flag, +plus tables of statistics about reads and writes to the files in the +volume. Do not combine this flag with the -fast or +-long flag. +
+

The output is ordered alphabetically by volume name and by default provides +the following information on a single line for each volume: +

Name +
Volume ID number + +
Type (the flag is RW for read/write, RO for +read-only, BK for backup) +
Size in kilobytes (1024 equals a megabyte) +
Number of files in the volume, if the -extended flag is +provided + +
Status on the file server machine, which is one of the following: +
+ +
On-line +
The volume is completely accessible to Cache Managers. + +
Off-line +
The volume is not accessible to Cache Managers, but does not seem to be +corrupted. This status appears while a volume is being dumped, for +example. + +
Off-line**needs salvage** +
The volume is not accessible to Cache Managers, because it seems to be +corrupted. Use the bos salvage or salvager +command to repair the corruption. +
+

If the following message appears instead of the previously listed +information, it indicates that a volume is not accessible to Cache Managers or +the vos command interpreter, for example because a clone is being +created. +

   **** Volume volume_ID is busy ****
+

If the following message appears instead of the previously listed +information, it indicates that the File Server is unable to attach the volume, +perhaps because it is seriously corrupted. The FileLog and +VolserLog log files in the /usr/afs/logs directory on +the file server machine possibly provide additional information; use the +bos getlog command to display them. +

   **** Could not attach volume volume_ID ****
+

(For instructions on salvaging a corrupted or unattached volume, see Salvaging Volumes.) +

The information about individual volumes is bracketed by summary +lines. The first line of output specifies the number of volumes in the +listing. The last line of output summarizes the number of volumes that +are online, offline, and busy, as in the following example: +

   
+   % vos listvol  fs2.abc.com /vicepb
+   Total number of volumes on server fs2.abc.com \
+                                       partition /vicepb : 66
+   sys                  1969534847 RW       1582 K On-line
+   sys.backup           1969535105 BK       1582 K On-line
+         .                   .     .         .   .    .
+         .                   .     .         .   .    .
+   user.pat             1969534536 RW      17518 K On-line
+   user.pat.backup      1969534538 BK      17537 K On-line
+   Total volumes onLine 66 ; Total volumes offLine 0 ;  Total busy 0
+   
+

Output with the -fast Flag +

+ +If you include the -fast flag displays only the volume ID number of +each volume, arranged in increasing numerical order, as in the following +example. The final line (which summarizes the number of on-line, +off-line, and busy volumes) is omitted. +

   
+   % vos listvol fs3.abc.com /vicepa -f
+   Total number of volumes on server fs3.abc.com  \
+                                       partition /vicepa: 37
+   50489902
+   50489904
+      .
+      .
+   35970325
+   49732810
+   
+

Output with the -long Flag + +

When you include the -long flag, , the output for each volume +includes all of the information in the default listing plus the +following. Each item in this list corresponds to a separate line of +output: +

The file server machine and partition that house the volume, as determined +by the command interpreter as the command runs, rather than derived from the +VLDB or the volume header. + + + + + + + + +
The volume ID numbers associated with the various versions of the +volume: read/write (RWrite), read-only (ROnly), +backup (Backup), and ReleaseClone (RClone). One +of them matches the volume ID number that appears on the first line of the +volume's output. If the value in the RWrite, +ROnly, or Backup field is 0 (zero), there is +no volume of that type. If there is currently no ReleaseClone, the +RClone field does not appear at all. + + +
The maximum space quota allotted to the read/write copy of the volume, +expressed in kilobyte blocks in the MaxQuota field. + + +
The date and time the volume was created, in the Creation +field. If the volume has been restored with the backup +diskrestore, backup volrestore, or vos restore +command, this is the restore time. + + +
The date and time when the contents of the volume last changed, in the +Last Update field. For read-only and backup volumes, it +matches the timestamp in the Creation field. + + +
The number of times the volume has been accessed for a fetch or store +operation since the later of the two following times: +
- 12:00 a.m. on the day the command is issued +
- The last time the volume changed location +
+

An example of the output when the -long flag is included: +

   
+   % vos listvol fs2.abc.com b -long
+   Total number of volumes on server fs2.abc.com 
+                                       partition /vicepb: 66
+         .                   .      .         .   .    .
+         .                   .      .         .   .    .
+   user.pat             1969534536 RW      17518 K On-line
+        fs2.abc.com /vicepb
+        RWrite 1969534536 ROnly 0        Backup 1969534538 
+        MaxQuota      20000 K
+        Creation    Mon Jun 12 09:02:25 1989
+        Last Update Thu Jan  4 17:39:34 1990
+        1573 accesses in the past day (i.e., vnode references)
+   user.pat.backup      1969534538 BK      17537 K On-line
+        fs2.abc.com /vicepb
+        RWrite 1969534536 ROnly 0        Backup 1969534538 
+        MaxQuota      20000 K
+        Creation    Fri Jan  5 06:37:59 1990
+        Last Update Fri Jan  5 06:37:59 1990
+        0 accesses in the past day (i.e., vnode references)
+	    .               .         .     .       .
+	    .               .         .     .       .
+   Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
+   
+

Output with the -extended Flag + +

When you include the -extended flag, the output for each volume +includes all of the information reported with the -long flag, plus +two tables of statistics: +

The table labeled Raw Read/Write Stats table summarizes the +number of times the volume has been accessed for reading or writing. +
The table labeled Writes Affecting Authorship table contains +information on writes made to files and directories in the specified +volume. +

An example of the output when the -extended flag is +included: +

   % vos listvol fs3.abc.com a -extended
+   common.bboards   1969535592 RW    23149 K used 9401 files On-line
+       fs3.abc.com /vicepa
+       RWrite 1969535592 ROnly          0 Backup 1969535594
+       MaxQuota      30000 K
+       Creation    Mon Mar  8 14:26:05 1999
+       Last Update Mon Apr 26 09:20:43 1999
+       11533 accesses in the past day (i.e., vnode references)
+   
+                         Raw Read/Write Stats
+             |-------------------------------------------|
+             |    Same Network     |    Diff Network     |
+             |----------|----------|----------|----------|
+             |  Total   |   Auth   |   Total  |   Auth   |
+             |----------|----------|----------|----------|
+   Reads     |      151 |      151 |     1092 |     1068 |
+   Writes    |        3 |        3 |      324 |      324 |
+             |-------------------------------------------|
+    
+                      Writes Affecting Authorship
+             |-------------------------------------------|
+             |   File Authorship   | Directory Authorship|
+             |----------|----------|----------|----------|
+             |   Same   |   Diff   |    Same  |   Diff   |
+             |----------|----------|----------|----------|
+   0-60 sec  |       92 |        0 |      100 |        4 |
+   1-10 min  |        1 |        0 |       14 |        6 |
+   10min-1hr |        0 |        0 |       19 |        4 |
+   1hr-1day  |        1 |        0 |       13 |        0 |
+   1day-1wk  |        1 |        0 |        1 |        0 |
+   > 1wk     |        0 |        0 |        0 |        0 |
+             |-------------------------------------------|
+   
+

Displaying One Volume's VLDB Entry and Volume Header

+ + + + + + + +

The vos examine command displays information from both the VLDB +and the volume header for a single volume. There is some redundancy in +the information from the two sources, which allows you to compare the VLDB and +volume header. +

Because the volume header for each version of a volume (read/write, +read-only, and backup) is different, you can specify which one to +display. Include the .readonly or +.backup extension on the volume name or ID argument +as appropriate. The information from the VLDB is the same for all three +versions. + + +

To display one volume's VLDB entry and volume header

Issue the vos examine command. +
```
   
+   % vos examine <volume name or ID>
+   
+
```
+
where +
+
e +
Is the shortest acceptable abbreviation of examine. +
volume name or ID +
Identifies one volume either by its complete name or volume ID +number. It can be a read/write, read-only, or backup type. Use +the .backup or .readonly extension if +appropriate. +
+

The top part of the output displays the same information from a volume +header as the vos listvol command with the -long flag, +as described following the instructions in To display volume headers. If you specify the read-only version of the volume +and it exists at more than one site, the output includes all of them. +The bottom part of the output lists the same information from the VLDB as the +vos listvldb command, as described following the instructions in To display VLDB entries. +

Below is an example for a volume whose VLDB entry is currently +locked. +

   
+   % vos examine user.terry
+   user.terry                    536870981 RW   3459 K On-line
+       fs3.abc.com /vicepa
+       Write 5360870981   ROnly          0  Backup 536870983
+       MaxQuota      40000 K
+       Creation    Mon Jun 12 15:22:06 1989
+       Last Update Fri Jun 16 09:34:35 1989
+       5719 accesses in the past day (i.e., vnode references)
+       RWrite: 5360870981   Backup: 536870983
+       number of sites -> 1
+          server fs3.abc.com partition /vicepa RW Site 
+       Volume is currently LOCKED
+   
+

Displaying the Name or Location of the Volume that Contains a File

This section explains how to learn the name, volume ID +number, or location of the volume that contains a file or directory. +

You can also use one piece of information about a volume (for example, its +name) to obtain other information about it (for example, its location). +The following list points you to the relevant instructions: +

To use a volume's name to learn the volume ID numbers of all its +existing versions, use the vos examine command as described in To display one volume's VLDB entry and volume header. +
You can also use the command to learn a volume's name by providing its +ID number. +
To use a volume's name or ID number to learn its location, use the +vos listvldb command as described in To display VLDB entries. + + + + + + +

+ + + + + + +

To display the name of the volume that contains a file

Issue the fs listquota command. +
```
   
+   % fs listquota [<dir/file path>]
+   
+
```
+
where +
+
lq +
Is an acceptable alias for listquota (and listq the +shortest acceptable abbreviation). +
dir/file path +
Names a directory or file housed in the volume for which to display the +name. Partial pathnames are interpreted relative to the current working +directory, which is the default if this argument is omitted. +
+

The following is an example of the output: +

   
+   % fs listquota /afs/abc.com/usr/terry
+   Volume Name     Quota    Used    % Used   Partition 
+   user.terry      15000    5071       34%         86%   
+   
+

+ + + + + + +

To display the ID number of the volume that contains a file

Issue the fs examine command. +
```
   
+   % fs examine [<dir/file path>]
+   
+
```
+
where +
+
exa +
Is the shortest acceptable abbreviation of examine. +
dir/file path +
Names a directory or file housed in the volume for which to display the +volume ID. Partial pathnames are interpreted relative to the current +working directory, which is the default if this argument is omitted. +
+

The following example illustrates how the output reports the volume ID +number in the vid field. +

   
+   % fs examine /afs/abc.com/usr/terry
+   Volume status for vid = 50489902 named user.terry
+   Current maximum quota is 15000
+   Current blocks used are 5073
+   The partition has 46383 blocks available out of 333305  
+   
+

Note:

+ + + + + + + +

To display the location of the volume that contains a file

Issue the fs whereis command to display the name of the file +server machine that houses the volume containing a file or directory. +
```
   
+   % fs whereis [<dir/file path>]
+   
+
```
+
where +
+
whe +
Is the shortest acceptable abbreviation of whereis. +
dir/file path +
Names a directory or file for which to report the location. Partial +pathnames are interpreted relative to the current working directory, which is +the default if this argument is omitted. +
+
The output displays the file server machine that houses the volume +containing the file, as in the following example: +
```
   
+   % fs whereis /afs/abc.com/user/terry
+   File /afs/abc.com/usr/terry is on host fs2.abc.com
+   
+
```
+
If you also want to know which partition houses the volume, first issue +the fs listquota command to display the volume's name. +For complete syntax, see To display the name of the volume that contains a file. +
```
   
+   % fs listquota [<dir/file path>]
+   
+
```
+
Then issue the vos listvldb command, providing the volume name +as the volume name or ID argument. For complete syntax and a +description of the output, see To display VLDB entries. +
```
   
+   % vos listvldb <volume name or ID>
+   
+
```
+

Moving Volumes

+ + +

There are three main reasons to move volumes: +

To place volumes on other partitions or machines temporarily while +repairing or replacing a disk or file server machine. +
To free space on a partition that is becoming overcrowded. + + + + + +One symptom of overcrowding is that users cannot to save files even though the +relevant volume is below its quota. The following error message +confirms the problem: +
```
   
+   afs: failed to store file (partition full)
+   
+
```
+
You can track available space on AFS server partitions by using the +scout or afsmonitor programs described in Monitoring and Auditing AFS Performance. +
A file server machine is becoming overloaded because it houses many more +volumes than other machines of the same size, or has volumes with more popular +files in them. +

+ + +To move a read/write volume, use the vos move command as described +in the following instructions. Before attempting to move the volume, +the vos command interpreter verifies that there is enough free +space for it on the destination partition. If not, it does not attempt +the move operation and prints the following message. +

   
+   vos: no space on target partition destination_part to move volume volume
+   
+

To move a read-only volume, you actually remove the volume from the current +site by issuing the vos remove command as described in To remove a volume and unmount it. Then define a new site and release the volume to it +by issuing the vos addsite and vos release commands as +described in To replicate a read/write volume (create a read-only volume). + + +

A backup volume always resides at the same site as its read/write source +volume, so you cannot move a backup volume except as part of moving the +read/write source. The vos move command automatically +deletes the backup version when you move a read/write volume. To create +a new backup volume at the new site as soon as the move operation completes, +issue the vos backup command as described in To create and mount a backup volume. + + +

To move a read/write volume

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+

Issue the vos move command to move the volume. Type it +on a single line; it appears on multiple lines here only for +legibility. +

   
+   % vos move <volume name or ID>  \
+       <machine name on source>  <partition name on source >  \
+       <machine name on destination>  <partition name on destination>
+   
+

where +

m +: Is the shortest acceptable abbreviation of move. +
volume name or ID +: Specifies the name or volume ID number of the read/write volume to +move. +
machine name on source +: Names the file server machine currently housing the volume. +
partition name on source +: Names the partition currently housing the volume. +
machine name on destination +: Names the file server machine to which to move the volume. +
partition name on destination +: Names the partition to which to move the volume. +

Note:

It is best not to halt a vos move operation before it completes, +because parts of the volume can be left on both the source and destination +machines. For more information, see the command's reference page +in the IBM AFS Administration Reference. +

(Optional) Issue the vos listvldb command to confirm +the success of the move. Complete instructions appear in To display VLDB entries. +
```
   
+   % vos listvldb <volume name or ID>
+   
+
```
+
If a backup version existed at the read/write volume's previous site, +create a new backup at the new site by issuing the vos backup +command, which is fully described in To create and mount a backup volume. +
```
   
+   % vos backup <volume name or ID>
+   
+
```
+

Synchronizing the VLDB and Volume Headers

+ + + +

AFS can provide transparent file access because the Volume Location +Database (VLDB) constantly tracks volume locations. When the Cache +Manager needs a file, it contacts the Volume Location (VL) Server, which reads +the VLDB for the current location of the volume containing the file. +Therefore, the VLDB must accurately reflect the state of volumes on the file +server machines at all times. The Volume Server and VL Server +automatically update a volume's VLDB entry when its status changes during +a vos operation, by performing the following series of +steps. +

The VL Server locks the VLDB entry. The lock advises +other operations not to manipulate any of the volume versions (read/write, +read-only, or backup), which prevents the inconsistency that can result from +multiple simultaneous operations. +
The VL Server sets an intention flag in the VLDB +entry that indicates the kind of operation to be performed. + + +This flag never appears in VLDB listings because it is for internal use +only. In case the operation terminates prematurely, this flag tells the +Salvager which operation was interrupted. (The Salvager then determines +the steps necessary either to complete the operation or return the volume to a +previous consistent state. For more information on salvaging, see Salvaging Volumes.) +
The Volume Server manipulates the volume. It usually +sets the Off-line flag in the volume header, which makes the volume +inaccessible to the File Server and other Volume Server operations during the +manipulation. When the operation completes, the volume is again marked +On-line. +
The VL Server records any changes resulting from the operation +in the VLDB entry. Once the operation is complete, it removes the +intention flag set in Step 2 and releases the lock set in Step 1. +

If a vos operation fails while the Volume Server is manipulating +the volume (corresponding to Step 3), the volume can be left in an intermediate state, which is +termed corruption. In this case, the Off-line or +Off-line**needs salvage** marker usually appears at the end of the +first line of output from the vos examine command. To repair +the corruption, run the Salvager before attempting to resynchronize the VLDB +and volume headers. For salvaging instructions, see Salvaging Volumes. +

More commonly, an interruption while flags are being set or removed +(corresponding to Step 1, Step 2, or Step 4) causes a discrepancy +between the VLDB and volume headers. To resynchronize the VLDB and +volumes, use the vos syncvldb and vos syncserv +commands. To achieve complete VLDB consistency, it is best to run the +vos syncvldb command on all file server machines in the cell, and +then run the vos syncserv command on all file server machines in +the cell. + + + +

There are several symptoms that indicate a volume operation failed: +

Error messages on the standard error stream or in server process log files +indicate that an operation terminated abnormally. Perhaps you had to +halt the operation before it completed (for instance, by using a signal such +as Ctrl-c), or a file server machine or server process was not +functioning when the operation ran. To determine if a machine or +process is still not functioning, issue the bos status command as +described in Displaying Process Status and Information from the BosConfig File. +
A subsequent vos operation fails because a previous failure +left a VLDB entry locked. Sometimes an error message reports that a +volume is locked. To display a list of locked volumes, use the +-locked flag on the vos listvldb command as described in +Displaying VLDB Entries. +
If the only problem with a volume is that its VLDB entry is locked, you +probably do not need to synchronize the entire VLDB. Instead use the +vos unlock or vos unlockvldb command to unlock the +entry, as described in Unlocking and Locking VLDB Entries. +
A subsequent vos operation fails because a previous failure +left a volume marked as offline. To check a volume's current +status, check the first line of output from the vos examine command +as described in Displaying One Volume's VLDB Entry and Volume Header. +

+ + + + + +

The vos syncvldb command corrects the information in the Volume +Location Database (VLDB) either about all volumes housed on a file server +machine, about the volumes on just one partition, or about a single +volume. If checking about one or more partitions, the command contacts +the Volume Server to obtain a list of the volumes that actually reside on each +partition. It then obtains the VLDB entry for each volume from the VL +Server. It changes the VLDB entry as necessary to reflect the state of +the volume on the partition. For example, it creates or updates a VLDB +entry when it finds a volume for which the VLDB entry is missing or +incomplete. However, if there is already a VLDB entry that defines a +different location for the volume, or there are irreconcilable conflicts with +other VLDB entries, it instead writes a message about the conflict to the +standard error stream. The command never removes volumes from the file +server machine. +

When checking a single volume's VLDB entry, the command also +automatically performs the operations invoked by the vos syncserv +command: it not only verifies that the VLDB entry is correct for the +specified volume type (read/write, backup, or read-only), but also checks that +any related volume types mentioned in the VLDB entry actually exist at the +site listed in the entry. + +

The vos syncserv command verifies that each volume type +(read/write, read-only, and backup) mentioned in a VLDB entry actually exists +at the site indicated in the entry. It checks all VLDB entries that +mention a site either on any of a file server machine's partitions or on +one partition. Note that command can end up inspecting sites other than +on the specified machine or partition, if there are read-only versions of the +volume at sites other than the read/write site. +

The command alters any incorrect information in the VLDB, unless there is +an irreconcilable conflict with other VLDB entries. In that case, it +writes a message to the standard error stream instead. The command +never removes volumes from their sites. + + + + +

To synchronize the VLDB with volume headers

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+

Issue the vos syncvldb command to make the VLDB +reflect the true state of all volumes on a machine or partition, or the state +of one volume. +

Note:

To synchronize the VLDB completely, issue the command repeatedly, +substituting each file server machine in your cell for the -server +argument in turn and omitting the -partition and -volume +arguments, before proceeding to Step 3. +

   % vos syncvldb -server <machine name> [-partition <partition name>]  [-volume <volume name or ID>]  [-verbose >> file]
+   
+

where +

syncv +: Is the shortest acceptable abbreviation of syncvldb. +
-server +: Names the file server machine housing the volumes for which to verify VLDB +entries. If you are also providing the -volume argument, +this argument must name the machine where the volume actually resides. +
-partition +: Identifies the partition (on the file server machine specified by the +-server argument) housing the volumes for which to verify VLDB +entries. In general, it is best to omit this argument so that either +the VLDB entries for all volumes on a server machine are corrected (if you do +not provide the -volume argument), or so that you do not need to +guarantee that the partition actually houses the volume named by the +-volume argument. +
-volume +: Specifies the name or volume ID number of a single volume for which to +verify the VLDB entry. +
-verbose >> file +: Directs a detailed trace to the file called file, which can be +either in AFS or on the local disk of the machine on which you are issuing the +command. The command often writes a large amount of output to the +standard output stream; writing it to a file enables you to examine the +output more carefully. +

Issue the vos syncserv command to inspect each +volume for which the VLDB lists a version at the specified site. +

+
Note: To synchronize the VLDB completely, issue the command repeatedly, +substituting each file server machine in your cell for the machine +name argument in turn and omitting the partition name +argument. +
+

   % vos syncserv <machine name> [<partition name>] [-v >> file]
+   
+

where +

syncs +: Is the shortest acceptable abbreviation of syncserv. +
machine name +: Names the file server machine mentioned in each VLDB entry to +check. +
partition name +: Identifies the partition mentioned in each VLDB entry to check. If +synchronizing the entire VLDB, omit this argument. +
-v >> file +: Directs a detailed trace to the file called file, which can be +either in AFS or on the local disk of the machine on which you are issuing the +command. The command often writes a large amount of output to the +standard output stream; writing it to a file enables you to examine the +output more carefully. +

Salvaging Volumes

+ + + + + + + + +

An unexpected interruption while the Volume Server or File Server is +manipulating the data in a volume can leave the volume in an intermediate +state (corrupted), rather than just creating a discrepancy between +the information in the VLDB and volume headers. For example, the +failure of the operation that saves changes to a file (by overwriting old data +with new) can leave the old and new data mixed together on the disk. +

If an operation halts because the Volume Server or File Server exits +unexpectedly, the BOS Server automatically shuts down all components of the +fs process and invokes the Salvager. The Salvager checks for +and repairs any inconsistencies it can. Sometimes, however, there are +symptoms of the following sort, which indicate corruption serious enough to +create problems but not serious enough to cause the File Server component to +fail. In these cases you can invoke the Salvager yourself by issuing +the bos salvage command. +

Symptom: A file appears in the output of the +ls command, but attempts to access the file fail with messages +indicating that it does not exist. +
Possible cause: The Volume Server or File Server exited in +the middle of a file-creation operation, after changing the directory +structure, but before actually storing data. (Other possible causes are +that the ACL on the directory does not grant the permissions you need to +access the file, or there is a process, machine, or network outage. +Check for these causes before assuming the file is corrupted.) +
Salvager's solution: Remove the file's entry +from the directory structure. +
Symptom: A volume is marked Off-line in the +output from the vos examine and vos listvol commands, or +attempts to access the volume fail. +
Possible cause: Two files or versions of a file are +sharing the same disk blocks because of an interrupted operation. The +File Server and Volume Server normally refuse to attach volumes that exhibit +this type of corruption, because it can be very dangerous. If the +Volume Server or File Server do attach the volume but are unsure of the status +of the affected disk blocks, they sometimes try to write yet more data +there. When they cannot perform the write, the data is lost. +This effect can cascade, causing loss of all data on a partition. +
Salvager's solution: Delete the data from the +corrupted disk blocks in preference to losing an entire partition. +
Symptom: There is less space available on the partition +than you expect based on the size statistic reported for each volume by the +vos listvol command. +
Possible cause: There are orphaned files and +directories. An orphaned element is completely inaccessible because it +is not referenced by any directory that can act as its parent (is higher in +the file tree). An orphaned element is not counted in the calculation +of a volume's size (or against its quota), even though it occupies space +on the server partition. +
Salvager's solution: By default, print a message to +the /usr/afs/logs/SalvageLog file reporting how many orphans were +found and the approximate number of kilobytes they are consuming. You +can use the -orphans argument to remove or attach orphaned elements +instead. See To salvage volumes. +

When you notice symptoms such as these, use the bos salvage +command to invoke the Salvager before corruption spreads. (Even though +it operates on volumes, the command belongs to the bos suite +because the BOS Server must coordinate the shutdown and restart of the Volume +Server and File Server with the Salvager. It shuts them down before the +Salvager starts, and automatically restarts them when the salvage operation +finishes.) +

All of the AFS data stored on a file server machine is inaccessible during +the salvage of one or more partitions. If you salvage just one volume, +it alone is inaccessible. +

When processing one or more partitions, the command restores consistency to +corrupted read/write volumes where possible. For read-only or backup +volumes, it inspects only the volume header: +

If the volume header is corrupted, the Salvager removes the volume +completely and records the removal in its log file, +/usr/afs/logs/SalvageLog. Issue the vos release +or vos backup command to create the read-only or backup volume +again. +
If the volume header is intact, the Salvager skips the volume (does not +check for corruption in the contents). However, if the File Server +notices corruption as it initializes, it sometimes refuses to attach the +volume or bring it online. In this case, it is simplest to remove the +volume by issuing the vos remove or vos zap +command. Then issue the vos release or vos backup +command to create it again. +

Combine the bos salvage command's arguments as indicated to +salvage different numbers of volumes: +

To salvage all volumes on a file server machine, combine the +-server argument and the -all flag. +
To salvage all volumes on one partition, combine the -server +and -partition arguments. +
To salvage only one read/write volume, combine the -server, +-partition, and -volume arguments. Only that +volume is inaccessible to Cache Managers, because the BOS Server does not +shutdown the File Server and Volume Server processes during the salvage of a +single volume. Do not name a read-only or backup volume with the +-volume argument. Instead, remove the volume, using the +vos remove or vos zap command. Then create a new +copy of the volume with the vos release or vos backup +command. +

The Salvager always writes a trace to the +/usr/afs/logs/SalvageLog file on the file server machine where it +runs. To record the trace in another file as well (either in AFS or on +the local disk of the machine where you issue the bos salvage +command), name the file with the -file argument. Or, to +display the trace on the standard output stream as it is written to the +/usr/afs/logs/SalvageLog file, include the -showlog +flag. +

By default, multiple Salvager subprocesses run in parallel: one for +each partition up to four, and four subprocesses for four or more +partitions. To increase or decrease the number of subprocesses running +in parallel, provide a positive integer value for the -parallel +argument. +

If there is more than one server partition on a physical disk, the Salvager +by default salvages them serially to avoid the inefficiency of constantly +moving the disk head from one partition to another. However, this +strategy is often not ideal if the partitions are configured as logical +volumes that span multiple disks. To force the Salvager to salvage +logical volumes in parallel, provide the string all as the value +for the -parallel argument. Provide a positive integer to +specify the number of subprocesses to run in parallel (for example, +-parallel 5all for five subprocesses), or omit the integer to run +up to four subprocesses, depending on the number of logical volumes being +salvaged. +

The Salvager creates temporary files as it runs, by default writing them to +the partition it is salvaging. The number of files can be quite large, +and if the partition is too full to accommodate them, the Salvager terminates +without completing the salvage operation (it always removes the temporary +files before exiting). Other Salvager subprocesses running at the same +time continue until they finish salvaging all other partitions where there is +enough disk space for temporary files. To complete the interrupted +salvage, reissue the command against the appropriate partitions, adding the +-tmpdir argument to redirect the temporary files to a local disk +directory that has enough space. +

The -orphans argument controls how the Salvager handles orphaned +files and directories that it finds on server partitions it is +salvaging. An orphaned element is completely inaccessible +because it is not referenced by the vnode of any directory that can act as its +parent (is higher in the filespace). Orphaned objects occupy space on +the server partition, but do not count against the volume's quota. +

During the salvage, the output of the bos status command reports +the following auxiliary status for the fs process: +

   
+   Salvaging file system
+   
+

+ + +

To salvage volumes

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos salvage command to salvage one or more +volumes. +
```
   
+   % bos salvage  -server <machine name>  [-partition <salvage partition>]  \
+                  [-volume <salvage volume number or volume name>]  \
+                  [-file salvage log output file]  [-all]  [-showlog]  \
+                  [-parallel <# of max parallel partition salvaging>]  \ 
+                  [-tmpdir <directory to place tmp files>]  \ 
+                  [-orphans <ignore | remove | attach>] 
+   
+
```
+
where +
+
-server +
Names the file server machine on which to salvage volumes. This +argument can be combined either with the -all flag, the +-partition argument, or both the -partition and +-volume arguments. +
-partition +
Names a single partition on which to salvage all volumes. The +-server argument must be provided along with this one. +
-volume +
Specifies the name or volume ID number of one read/write volume to +salvage. Combine this argument with the -server and +-partition arguments. +
-file +
Specifies the complete pathname of a file into which to write a trace of +the salvage operation, in addition to the /usr/afs/logs/SalvageLog +file on the server machine. If the file pathname is local, the trace is +written to the specified file on the local disk of the machine where the +bos salvage command is issued. If the -volume +argument is included, the file can be in AFS, though not in the volume being +salvaged. Do not combine this argument with the -showlog +flag. +
-all +
Salvages all volumes on all of the partitions on the machine named by the +-server argument. +
-showlog +
Displays the trace of the salvage operation on the standard output stream, +as well as writing it to the /usr/afs/logs/SalvageLog file. +
-parallel +
Specifies the maximum number of Salvager subprocesses to run in +parallel. Provide one of three values: +
- An integer from the range 1 to 32. A value of +1 means that a single Salvager process salvages the partitions +sequentially. +
- The string all to run up to four Salvager subprocesses in +parallel on partitions formatted as logical volumes that span multiple +physical disks. Use this value only with such logical volumes. +
- The string all followed immediately (with no intervening space) +by an integer from the range 1 to 32, to run the +specified number of Salvager subprocesses in parallel on partitions formatted +as logical volumes. Use this value only with such logical +volumes. +
+
The BOS Server never starts more Salvager subprocesses than there are +partitions, and always starts only one process to salvage a single +volume. If this argument is omitted, up to four Salvager subprocesses +run in parallel. +
-tmpdir +
Specifies the full pathname of a local disk directory to which the +Salvager process writes temporary files as it runs. By default, it +writes them to the partition it is currently salvaging. +
-orphans +
Controls how the Salvager handles orphaned files and directories. +Choose one of the following three values: +
+
ignore +
Leaves the orphaned objects on the disk, but prints a message to the +/usr/afs/logs/SalvageLog file reporting how many orphans were found +and the approximate number of kilobytes they are consuming. This is the +default if you omit the -orphans argument. +
remove +
Removes the orphaned objects, and prints a message to the +/usr/afs/logs/SalvageLog file reporting how many orphans were +removed and the approximate number of kilobytes they were consuming. +
attach +
Attaches the orphaned objects by creating a reference to them in the vnode +of the volume's root directory. Since each object's actual +name is now lost, the Salvager assigns each one a name of the following +form: +
+
_ _ORPHANFILE_ _.index for files +
_ _ORPHANDIR_ _.index for directories +
+
+
where index is a two-digit number that uniquely identifies each +object. The orphans are charged against the volume's quota and +appear in the output of the ls command issued against the +volume's root directory. +
+
+

Setting and Displaying Volume Quota and Current Size

+ + +

Every AFS volume has an associated quota which limits the +volume's size. The default quota for a newly created volume is +5,000 kilobyte blocks (slightly less that 5 MB). When a volume reaches +its quota, the File Server rejects attempts to create new files or directories +in it. If an application is writing data into an existing file in a +full volume, the File Server allows a defined overage (by default, 1 +MB). (You can use the fileserver command's +-spare or -pctspare argument to change the default +overage; see the command's reference page in the IBM AFS +Administration Reference.) +

To set a quota other than 5000 KB as you create a volume, include the +-maxquota argument to the vos create command, as +described in Creating Read/write Volumes. To modify an existing volume's quota, issue +either the fs setquota or the fs setvol command as +described in the following instructions. Do not set an existing +volume's quota lower than its current size. +

In general, smaller volumes are easier to administer than larger +ones. If you need to move volumes, say for load-balancing purposes, it +is easier to find enough free space on other partitions for small +volumes. Move operations complete more quickly for small volumes, +reducing the potential for outages or other errors to interrupt the +move. AFS supports a maximum volume size, which can vary for different +AFS releases; see the IBM AFS Release Notes for the version +you are using. Also, the size of a partition or logical places an +absolute limit on volume size, because a volume cannot span multiple +partitions or logical volumes. +

It is generally safe to overpack partitions by putting more volumes on them +than can actually fit if all the volumes reach their maximum quota. +However, only experience determines to what degree overpacking works in your +cell. It depends on what kind of quota you assign to volumes +(particularly user volumes, which are more likely than system volumes to grow +unpredictably) and how much information people generate and store in +comparison to their quota. +

There are several commands that display a volume's quota, as described +in the following instructions. They differ in how much related +information they produce. +

To set quota for a single volume

+ + + + + +

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the fs setquota command to set the volume's maximum +quota. +
```
   
+   % fs setquota [<dir/file path>] -max <max quota in kbytes>
+   
+
```
+
where +
+
sq +
Is an acceptable alias for setquota. +
dir/file path +
Names a file or directory in the volume for which to set the indicated +quota. Partial pathnames are interpreted relative to the current +working directory, which is the default if you omit this argument. +
Specify the read/write path to the file or directory, to avoid the failure +that results when you attempt to change a read-only volume. By +convention, you indicate the read/write path 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 Rules of Mount Point Traversal. +
max quota in kbytes +
Sets the volume's quota, expressed in kilobyte blocks +(1024 equals a megabyte). A value of 0 grants an +unlimited quota, but the size of the partition imposes an absolute +limit. You must include the -max switch if omitting the +dir/file path argument (to set the quota on the volume that houses +the current working directory). +
+

To set maximum quota on one or more volumes

+ + + + +

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the fs setvol command to set the quota on one or more +volumes. +
```
   
+   % fs setvol [<dir/file path>⁺] -max <disk space quota in 1K units>
+   
+
```
+
where +
+
sv +
Is an acceptable alias for setvol. +
dir/file path +
Names one file or directory that resides in each volume for which to set +the indicated quota. Partial pathnames are interpreted relative to the +current working directory, which is the default if you omit this +argument. +
disk space quota in 1K units +
Sets the maximum quota on each volume, expressed in kilobytes blocks +(1024 equals a megabyte). A value of 0 grants an +unlimited quota, but the size of the partition does impose an absolute +limit. +
+

+ + + + +

To display percent quota used

Issue the fs quota command. +
```
   
+   % fs quota [<dir/file path>⁺]
+   
+
```
+
where +
+
q +
Is the shortest acceptable abbreviation of quota. +
dir/file path +
Names a directory or file in each volume for which to display percent +quota used. Partial pathnames are interpreted relative to the current +working directory, which is the default if you omit this argument. +
+

The following example illustrates the output produced by this +command: +

   
+   % fs quota /afs/abc.com/usr/terry
+   34% of quota used.
+   
+

+ + + + + + +

To display quota, current size, and other information

Issue the fs listquota command. +
```
   
+   % fs listquota [<dir/file path>⁺]
+   
+
```
+
where +
+
lq +
Is an alias for listquota. +
dir/file path +
Names a directory or file in each volume for which to display quota along +with volume name and current space usage. Partial pathnames are +interpreted relative to the current working directory, which is the default if +you omit this argument. +
+

As illustrated in the following example, the output reports the +volume's name, its quota and current size (both in kilobyte units), the +percent quota used, and the percentage of space on the volume's host +partition that is used. +

   
+   % fs listquota /afs/abc.com/usr/terry
+   Volume Name     Quota    Used    % Used   Partition 
+   user.terry      15000    5071       34%         86%   
+   
+

+ + + + + + + +

To display quota, current size, and more partition information

Issue the fs examine command. +
```
   
+   % fs examine [<dir/file path>⁺]
+   
+
```
+
where +
+
exa +
Is the shortest acceptable abbreviation of examine. +
dir/file path +
Names a directory or file in each volume for which to display quota +information and information about the host partition. Partial pathnames +are interpreted relative to the current working directory, which is the +default if you omit this argument. +
+

As illustrated in the following example, the output displays the +volume's volume ID number and name, its quota and current size (both in +kilobyte units), and the free and total number of kilobyte blocks on the +volume's host partition. +

   
+   % fs examine /afs/abc.com/usr/terry
+   Volume status for vid = 50489902 named user.terry
+   Current maximum quota is 15000
+   Current blocks used are 5073
+   The partition has 46383 blocks available out of 333305   
+   
+

Note:

Removing Volumes and their Mount Points

+ + + + + +

To remove a volume from its site and its record from the VLDB, use the +vos remove command. Use it to remove any of the three types +of volumes; the effect depends on the type. +

If you indicate the read/write volume by specifying the volume's base +name without a .readonly or .backup +extension, the command removes both the read/write and associated backup +volume from the partition that houses them. + + +You do not need to provide the -server and -partition +arguments, because there can be only one read/write site. The site +information is also removed from the VLDB entry, and the site count (reported +by the vos examine and vos listvldb commands as +number of sites) decrements by one. The read/write and +backup volume ID numbers no longer appear in the output from the vos +examine and vos listvldb commands, but they are preserved +internally. Read-only sites, if any, are not affected, but cannot be +changed unless a read/write site is again defined. The entire VLDB +entry is removed if there are no read-only sites. +
If there are no read-only copies left, it is best to remove the +volume's mount point to prevent attempts to access the volume's +contents. Do not remove the mount point if copies of the read-only +volume remain. +
If you indicate a read-only volume by including the +.readonly extension on its name, it is removed from the +partition that houses it, and the corresponding site information is removed +from the VLDB entry. The site count reported by the vos +examine and vos listvldb commands as number of +sites decrements by one for each volume you remove. + +
If there is more than one read-only site, you must include the +-server argument (and optionally -partition argument) to +specify the site from which to remove the volume. If there is only one +read-only site, the volume name is sufficient; if no read/write volume +exists in this case, the entire VLDB entry is removed. +
It is not generally appropriate to remove the volume's mount point +when removing a read-only volume, especially if the read/write version of the +volume still exists. If the read/write version no longer exists, remove +the mount point as described in Step 5 of To remove a volume and unmount it. +
If you indicate a backup volume by including the .backup +extension on its name, it is removed from the partition that houses it and its +site information is removed from the VLDB entry. You do not need to +provide the -server and -partition arguments, because +there can be only one backup site. The backup volume ID number no +longer appears in the output from the vos examine or vos +listvldb command, but is preserved internally. +
In the standard configuration, there is a separate mount point for the +backup version of a user volume. Remember to remove the mount point to +prevent attempt to access the nonexistent volume's contents. +

Other Removal Commands

+ +

The vos remove command is almost always the appropriate way to +remove a volume, because it automatically removes a volume's VLDB entry +and both the volume header and all data from the partition. If either +the VLDB entry or volume header does not exist, it is sometimes necessary to +use other commands that remove only the remaining element. Do not use +these commands in the normal case when both the VLDB entry and the volume +header exist, because by definition they create discrepancies between +them. For details on the commands' syntax, see their reference +pages in the IBM AFS Administration Reference. +

The vos zap command removes a volume from its site by removing +the volume header and volume data for which a VLDB entry no longer +exists. + + +You can tell a VLDB entry is missing if the vos listvol command +displays the volume header but the vos examine or vos +listvldb command cannot locate the VLDB entry. You must run this +command to correct the discrepancy, because the vos syncvldb and +vos syncserv commands never remove volume headers. +

The vos remsite command removes a read-only site definition from +the VLDB without affecting the volume on the file server machine. + + +Use this command when you have mistakenly issued the vos addsite +command to define a read-only site, but have not yet issued the vos +release command to release the volume to the site. If you have +actually released a volume to the site, use the vos remove command +instead. +

The vos delentry command removes the entire VLDB entry that +mentions the volume you specify. + + +If versions of the volume actually exist on file server machines, they are not +affected. This command is useful if you know for certain that a volume +removal was not recorded in the VLDB (perhaps you used the vos zap +command during an emergency), and do not want to take the time to +resynchronize the entire VLDB with the vos syncvldb and vos +syncserv commands. +

To remove a volume and unmount it

+ +

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If removing the volume's mount point, verify that you have the +d (delete) permission on its parent directory's +ACL. If necessary, issue the fs listacl command, which is +fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
(Optional) Dump the volume to a file or to tape, in +case you want to restore it later. To copy the volume's contents +to a file, use the vos dump command as instructed in Dumping and Restoring Volumes. You can then copy the file to tape using a +third-party backup utility or an archiving utility such as the UNIX +tar command. +
Alternatively, use the AFS Backup System to create a tape copy. In +this case, it can be convenient to create a temporary volume set that includes +only the volume of interest. Temporary volume sets are not recorded in +the Backup Database, and so do not clutter database with records for volume +sets that you use only once. For instructions, see To create a dump. + + +
Issue the vos remove command to remove the +volume. If removing a read-only volume from multiple sites, repeat the +command for each one. +
```
   
+   % vos remove [-server machine name>]  [-partition <partition name>]  \
+                -id <volume name or ID>
+   
+
```
+
where +
+
remo +
Is the shortest acceptable abbreviation of remove. +
-server +
Specifies the file server machine on which the volume resides. It +is necessary only when the -id argument names a read-only volume +that exists at multiple sites. +
-partition +
Specifies the partition on machine name where the volume +resides. It is necessary only when the -id argument names a +read-only volume that exists at multiple sites. Provide the +-server argument along with this one. +
-id +
Identifies the volume to remove, either by its complete name or volume ID +number. If identifying a read-only or backup volume by name, include +the appropriate extension (.readonly or +.backup). +
+ + +
If you are removing the last existing version of the volume, +issue the fs rmmount command remove the corresponding mount +point. Complete instructions appear in To remove a volume and unmount it. +
If you are removing a backup volume that is mounted in the conventional way +(at a subdirectory of its read/write volume's root directory), then +removing the source volume's mount point in this step is sufficient to +remove the backup volume's mount point. If you mounted the backup +at a completely separate directory, you need to repeat this step for the +backup volume's mount point. +
```
   
+   % fs rmmount <directory>
+   
+
```
+
(Optional) If you created a dump file in Step 3, transfer it to tape. The preferred method is to use +the AFS Backup System, which is described in Configuring the AFS Backup System and Backing Up and Restoring AFS Data. +

Dumping and Restoring Volumes

+ + +

Dumping a volume with the vos dump command converts +its contents into ASCII format and writes them to the file you specify. +The vos restore command places a dump file's contents into a +volume after converting them into the volume format appropriate for the +indicated file server machine. +

About Dumping Volumes

+ + + + + + +

Dumping a volume can be useful in several situations, including the +following: +

You want to back it up to tape, perhaps by using a third-party backup +utility. To facilitate this type of backup operation, the vos +dump command can write to a named pipe. To learn about using the +AFS Backup System instead, see Configuring the AFS Backup System and Backing Up and Restoring AFS Data. +
You are removing the volume from your cell (perhaps because its owner is +leaving your cell). The vos dump command enables you to +create a copy for safekeeping without incurring the overhead of the Backup +System. For complete instructions on removing a volume, see Removing Volumes and their Mount Points. +
You want to create a copy of the volume for safekeeping on a non-AFS +server partition, perhaps while you move the actual volume to another machine +or perform maintenance tasks on the partition that houses the volume. +
You need to replace a corrupted read/write volume. If an +uncorrupted read-only or backup version of the volume exists, dump it and +restore the data into the read/write volume, overwriting the corrupted +contents. +
You want to copy or transfer the contents of the volume to another +cell. You cannot use the vos move command, because AFS +supports volume moves only between file server machines that belong to the +same cell. +
You want to have another read/write copy of the volume's +contents. The second volume must have a different name than the +original one. If you want the contents of the two volumes to remain +identical, you must update them both manually. AFS provides no facility +for keeping read/write volumes synchronized in this way. +
You want a copy of only the files and directories in the volume with +modification time stamps after a certain date. The vos dump +command can create an incremental dump file as described in Step 3 of the following instructions. +

+ + + +

You can use the vos dump command to create a full +dump, which contains the complete contents of the volume at the time you +issue the command, or an incremental dump, which contains only +those files and directories with modification timestamps (as displayed by the +ls -l command) that are later than a date and time you +specify. See Step 3 of the following instructions. +

Dumping a volume does not change its VLDB entry or permanently affect its +status on the file server machine, but the volume's contents are +inaccessible during the dump operation. To avoid interrupting access to +the volume, it is generally best to dump the volume's backup version, +just after using the vos backup or vos backupsys command +to create a new backup version. +

If you do not provide a filename into which to write the dump, the vos +dump command directs the output to the standard output stream. +You can pipe it directly to the vos restore command if you +wish. +

Because a volume dump file is in ASCII format, you can read its contents +using a text editor or a command such as the cat command. +However, dump files sometimes contain special characters that do not have +alphanumeric correlates, which can cause problems for some display +programs. +

By default, the vos command interpreter consults the Volume +Location Database (VLDB) to learn the volume's location, so the +-server and -partition arguments are not +required. If the -id argument identifies a read-only volume +that resides at multiple sites, then the command dumps the version from just +one of them (normally, the one listed first in the volume's VLDB entry as +reported by the vos examine or vos listvldb +command). To dump the read-only volume from a particular site, use the +-server and -partition arguments to specify the +site. To bypass the VLDB lookup entirely, provide a volume ID number +(rather than a volume name) as the value for the -id argument, +along with the -server and -partition arguments. +This makes it possible to dump a volume for which there is no VLDB +entry. + + +

To dump a volume

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Verify that you have the permissions necessary to create the dump +file. If placing it in AFS, you must have the i +(insert) permission on the ACL of the file's directory. +If necessary, issue the fs listacl command, which is fully +described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
Issue the vos dump command to dump the +volume. +
```
   
+   % vos dump -id <volume name or ID> [-time <dump from time>]  [-file <arg>]  [-server <server>]  [-partition <partition>]
+   
+
```
+
where +
+
-id +
Identifies the volume to be dumped by its complete name or volume ID +number. If you want to dump the read-only or backup version, specify +its volume ID number or add the appropriate extension +(.readonly or .backup) to the name. +
To bypass the normal VLDB lookup of the volume's location, provide the +volume ID number and combine this argument with the -server and +-partition arguments. +
-time +
Specifies whether the dump is full or incremental. Omit this +argument to create a full dump, or provide one of three acceptable +values: +
- The value 0 (zero) to create a full dump. +
- A date in the format +mm/dd/yyyy (month, day +and year) to create an incremental dump that includes only files and +directories with modification timestamps later than midnight (12:00 +a.m.) on the indicated date. 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 2038. The command interpreter automatically reduces later dates to +the maximum value. An example is 01/13/1999. +
- A date and time in the format +"mm/dd/yyyy +hh:MM" to create an +incremental dump that includes only files and directories with modification +timestamps later than the specified date and time. The date format is +the same as for a date alone. Express the time as hours and minutes +(hh:MM) in 24-hour format (for example, +20:30 is 8:30 p.m.). Surround the +entire expression with double quotes (" ") because it contains a space. +An example is "01/13/1999 22:30". +
+
-file +
Specifies the pathname of the file to which to write the dump. The +file can be in AFS, but not in the volume being dumped. A partial +pathname is interpreted relative to the current working directory. Omit +this argument to direct the dump to the standard output stream. +
-server +
Specifies the file server machine on which the volume resides. +Provide the -partition argument along with this one. +
-partition +
Specifies the partition on which the volume resides. Provide the +-server argument along with this one. +
+

About Restoring Volumes

+ + +

Although you can dump any of the three types of volumes (read/write, +read-only, or backup), you can restore a dump file to the file system only as +a read/write volume, using the vos restore command. The +command automatically translates the dump file's contents from ASCII back +into the volume format appropriate for the file server machine that stores the +restored version. As with the vos dump command, you can +restore a dump file via a named pipe, which facilitates interoperation with +third-party backup utilities. +

You can restore the contents of a dump file in one of two basic +ways. In either case, you must restore a full dump of the volume before +restoring any incremental dumps. Any incremental dumps that you then +restore must have been created after the full dump. If there is more +than one incremental dump, you must restore them in the order they were +created. +

You can restore volume data into a brand new volume with a new name and at +a location that you specify. See To restore a dump into a new volume and mount it. +
You can assign a volume ID number as you restore the volume, though it is +best to have the Volume Server allocate a volume number automatically. +The most common reason for specifying the volume ID is that a volume's +VLDB entry has disappeared for some reason, but you know the former read/write +volume ID number and want to reuse it. +
You can restore volume data into an existing volume (usually the one that +was previously dumped), overwriting its current contents. This is +convenient if the current contents are corrupted or otherwise incorrect, +because it allows you to replace them with a coherent version from the past or +from one of the volume's clones. See To restore a dump file, overwriting an existing volume. +
Provide the -overwrite argument to preconfirm that you wish to +overwrite the volume's contents, and to specify whether you are restoring +a full or incremental dump. If you omit the -overwrite +argument, the Volume Server generates the following prompt to confirm that you +want to overwrite the existing volume with either a full (f) or +incremental (i) dump: +
```
   
+   Do you want to do a full/incremental restore or abort? [fia](a):
+   
+
```
+
If you pipe in the dump file via the standard input stream instead of using +the -file argument to name it, you must include the +-overwrite argument because there is nowhere for the Volume Server +to display the prompt in this case. +
You can move the volume to a new site as you overwrite it with a full dump, +by using the -server and -partition arguments to specify +the new site. You cannot move the volume when restoring an incremental +dump. +

The vos restore command sets the restored volume's creation +date in the volume header to the time of the restore operation, as reported in +the Creation field in the output from the vos examine +and vos listvol commands. + + +

To restore a dump into a new volume and mount it

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Verify that you have permissions needed to read the dump file and to mount +the new volume. If the dump file resides in AFS, you need the +r (read) permission on the ACL of its directory. +You need the i (insert) and a +(administer) permissions on the ACL of the directory where you are +mounting the new volume. If necessary, issue the fs listacl +command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
Select a site (disk partition on a file server machine) for the new +volume. If your cell groups different types of volumes onto different +file server machines, that can guide your decision. It often makes +sense to put the volume on the emptiest partition that meets your other +criteria. To display how much space is available on a file server +machine's partitions, use the vos partinfo command, which is +described fully in Creating Read/write Volumes. +
```
   
+   % vos partinfo <machine name> [<partition name>]
+   
+
```
+
Issue the vos restore command to create a new volume +and restore the dump file into it. Type it on a single line; it +appears on multiple lines here only for legibility. +
```
   
+   % vos restore <machine name> <partition name>  \
+                 <name of volume to be restored>   \
+                 [-file <dump file>] [-id <volume ID>]
+   
+
```
+
where +
+
res +
Is the shortest acceptable abbreviation of restore. +
machine name +
Names the file server machine on which to create the new volume. +
partition name +
Names the partition on which to create the new volume. +
name of volume to be restored +
Names the new read/write volume, which must not already have a VLDB +entry. It can be up to 22 characters in length. +
-file +
Is the dump file to restore. Partial pathnames are interpreted with +respect to the current working directory. Omit this argument if using a +pipe to read in the dump file from the standard input stream. +
-volume +
Specifies the new volume's ID number. It is appropriate only +if you are restoring a volume that no longer exists and want to use the volume +ID number it had previously. +
+ + +
Issue the fs mkmount command to mount the new volume, making +its contents accessible. Complete instructions appear in To create a regular or read/write mount point. +
```
   
+   % fs mkmount <directory> <volume name>
+   
+
```
+
(Optional) Issue the fs lsmount command to verify +that the mount point refers to the correct volume. Complete +instructions appear in To display a mount point. +
```
   
+   % fs lsmount <directory>
+   
+
```
+

+ + +

To restore a dump file, overwriting an existing volume

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Verify that you have permissions needed to read the dump file. If +it resides in AFS, you need the r (read) permission on +the ACL of its directory. If necessary, issue the fs listacl +command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
Restore the contents of the dump file into a read/write volume, +overwriting the current contents. The volume retains its current volume +ID number. Type it on a single line; it appears on multiple lines +here only for legibility. +
```
   
+   % vos restore <machine name> <partition name>  \
+                 <name of volume to be restored>   \
+                 [-file <dump  file>]  \
+                 -overwrite <full | incremental>
+   
+
```
+
where +
+
res +
Is the shortest acceptable abbreviation of restore. +
machine name +
Names the file server machine where the volume already exists, or the +machine to which to move it. In the latter case, the value for the +-overwrite argument must be full. +
partition name +
Names the partition where the volume already exists, or the partition to +which to move it. In the latter case, the value for the +-overwrite argument must be full. +
name of volume to be restored +
Names the read/write volume to overwrite with the contents of the dump +file. +
-file +
Is the dump file to restore. Partial pathnames are interpreted with +respect to the current working directory. Omit this argument if using a +pipe to read in the dump file from the standard input stream; in this +case, you must provide the -overwrite argument. +
-overwrite +
Preconfirms that you want to overwrite the existing volume and specifies +which type of dump file you are restoring. Provide one of the following +values: +
- f or full if restoring a full dump file +
- i or incremental if restoring an incremental dump +file. This value is not acceptable if you are moving the volume while +restoring it. +
- a to terminate the restore operation +
+
+
If the volume is replicated, issue the vos release command to +release the newly restored contents to read-only sites. Complete +instructions appear in Replicating Volumes (Creating Read-only Volumes). +
```
   
+   % vos release <volume name or ID>
+   
+
```
+
Issue the vos backup command to create a new backup version of +the volume. Complete instructions appear in Creating Backup Volumes. +
```
   
+   % vos backup <volume name or ID>
+   
+
```
+

Renaming Volumes

+ + + + +

You can use the vos rename command to rename a volume. +For example, it is appropriate to rename a user's home volume if you use +the user.username convention for user volume names +and you change the username. (For complete instructions for changing +usernames, see Changing Usernames.) +

+ + + +The vos rename command accepts only read/write volume names, but +automatically changes the names of the associated read-only and backup +volumes. As directed in the following instructions, you need to replace +the volume's current mount point with a new one that reflects the name +change. + + +

To rename a volume

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Verify that you have the a (administer), +d (delete), and i (insert) access +permissions for the directory in which you are replacing the volume's +mount point. If necessary, issue the fs listacl command, +which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
Issue the vos rename command to rename the +volume. +
```
   
+   % vos rename <old volume name> <new volume name>
+   
+
```
+
where +
+
ren +
Is the shortest acceptable abbreviation of rename. +
old volume name +
Is the current name of a read/write volume. +
new volume name +
Is the new name for the volume. It cannot be more than 22 +characters in length. +
+
If there is no Volume Location Database (VLDB) entry for the specified +current volume name, the command fails with the following error message: +
+
```
   
+   vos: Could not find entry for volume old_volume_name. 
+   
+
```
+ + +
Issue the fs rmmount command to remove the mount point that +refers to the volume's old name. Complete instructions appear in To remove a mount point. +
```
   
+   % fs rmmount <directory>
+   
+
```
+ + +
Issue the fs mkmount to create a mount point that indicates the +volume's new name. Complete instructions appear in To create a regular or read/write mount point. +
```
   
+   % fs mkmount <directory> <volume name> [-rw]
+    
+
```
+

Unlocking and Locking VLDB Entries

As detailed in Synchronizing the VLDB and Volume Headers, The Volume Location (VL) Server locks the +Volume Location Database (VLDB) entry for a volume before the Volume Server +executes any operation on it. No other operation can affect a volume +with a locked VLDB entry, so the lock prevents the inconsistency or corruption +that can result from multiple simultaneous operations on a volume. + + + + + + +

To verify that a VLDB entry is locked, issue the vos listvldb +command as described in To display VLDB entries. The command has a -locked flag that +displays locked entries only. If the VLDB entry is locked, the string +Volume is currently LOCKED appears on the last line of the +volume's output. +

To lock a VLDB entry yourself, use the vos lock command. +This is useful when you suspect something is wrong with a volume and you want +to prevent any changes to it while you are investigating the problem. +

To unlock a locked VLDB entry, issue the vos unlock command, +which unlocks a single VLDB entry, or the vos unlockvldb command, +which unlocks potentially many entries. This is useful when a volume +operation fails prematurely and leaves a VLDB entry locked, preventing you +from acting to correct the problems resulting from the failure. + + +

To lock a VLDB entry

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the vos lock to lock the entry. +
```
   
+   % vos lock <volume name or ID>
+   
+
```
+
where +
+
lo +
Is the shortest acceptable abbreviation of lock. +
volume name or ID +
Identifies the volume to be locked, either by its complete name or volume +ID number. It can be any of the three versions of the volume. +
+

+ + +

To unlock a single VLDB entry

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the vos unlock command to unlock the entry. +
```
   % vos unlock <volume name or ID>
+   
+
```
+
where +
+
unlock +
Must be typed in full. +
volume name or ID +
Identifies the volume to be unlocked, either by its complete name or +volume ID number. It can be any of the three versions of the +volume. +
+

+ + +

To unlock multiple VLDB entries

Verify that you are listed in the /usr/afs/etc/UserList +file. If necessary, issue the bos listusers command, which +is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the vos unlockvldb command to unlock the desired +entries. +
```
   
+   % vos unlockvldb [<machine name>] [<partition name>]
+   
+
```
+
where +
+
unlockv +
Is the shortest acceptable abbreviation of unlockvldb. +
machine name +
Specifies a file server machine. Provide this argument alone to +unlock all VLDB entries that mention the machine in a site definition. +Omit both this argument and the partition name argument to unlock all +VLDB entries. +
partition name +
Specifies a partition. Provide this argument alone to unlock all +VLDB entries that mention the partition (on any machine) in a site +definition. Omit both this argument and the machine name +argument to unlock all VLDB entries. +
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd011.htm b/doc/html/AdminGuide/auagd011.htm new file mode 100644 index 0000000..d9853ee --- /dev/null +++ b/doc/html/AdminGuide/auagd011.htm @@ -0,0 +1,2557 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Configuring the AFS Backup System

The AFS Backup System helps you to create backup copies of +data from AFS volumes and to restore data to the file system if it is lost or +corrupted. This chapter explains how to configure the Backup +System. For instructions on backing up and restoring data and +displaying dump records, see Backing Up and Restoring AFS Data. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + + + + + + + + +
Determine tape capacity and filemark size + fms +
Define Tape Coordinator entry in Backup Database + backup addhost +
Remove Tape Coordinator entry from Backup Database + backup delhost +
Display Tape Coordinator entries from Backup Database + backup listhosts +
Create volume set + backup addvolset +
Add volume entry to volume set + backup addvolentry +
List volume sets and entries + backup listvolsets +
Delete volume set from Backup Database + backup delvolset +
Delete volume entry from volume set + backup delvolentry +
Define dump level + backup adddump +
Change expiration date on existing dump level + backup setexp +
Delete dump level from dump hierarchy + backup deldump +
Display dump hierarchy + backup listdumps +
Label tape + backup labeltape +
Read label on tape + backup readlabel +
+

Introduction to Backup System Features

+ +

The AFS Backup System is highly flexible, enabling you to control most +aspects of the backup process, including how often backups are performed, +which volumes are backed up, and whether to dump all of the data in a volume +or just the data that has changed since the last dump operation. You +can also take advantage of several features that automate much of the backup +process. +

To administer and use the Backup System most efficiently, it helps to be +familiar with its basic features, which are described in the following +sections. For pointers to instructions for implementing the features as +you configure the Backup System in your cell, see Overview of Backup System Configuration. +

Volume Sets and Volume Entries

+ + + + + +

When you back up AFS data, you specify which data to include in terms of +complete volumes rather than individual files. More precisely, you +define groups of volumes called volume sets, each of which includes +one or more volumes that you want to back up in a single operation. You +must include a volume in a volume set to back it up, because the command that +backs up data (the backup dump command) does not accept individual +volume names. +

A volume set consists of one or more volume entries, each of +which specifies which volumes to back up based on their location (file server +machine and partition) and volume name. You can use a wildcard notation +to include all volumes that share a location, a common character string in +their names, or both. +

For instructions on creating and removing volume sets and volume entries, +see Defining and Displaying Volume Sets and Volume Entries. +

Dumps and Dump Sets

+ + + + + + + + + + +

A dump is the collection of data that results from backing up a +volume set. A full dump includes all of the data in every +volume in the volume set, as it exists at the time of the dump +operation. An incremental dump includes only some of the +data from the volumes in the volume set, namely those files and directory +structures that have changed since a specified previous dump operation was +performed. The previous dump is referred to as the incremental +dump's parent dump, and it can be either a full dump or an +incremental dump itself. +

A dump set is a collection of one or more dumps stored together +on one or more tapes. The first dump in the dump set is the +initial dump, and any subsequent dump added onto the end of an +existing dump set is an appended dump. Appending dumps is +always optional, but maximizes use of a tape's capacity. In +contrast, creating only initial dumps can result in many partially filled +tapes, because an initial dump must always start on a new tape, but does not +necessarily extend to the end of the tape. Appended dumps do not have +to be related to one another or to the initial dump (they do not have to be +dumps of the same or related volume sets), but well-planned appending can +reduce the number of times you have to change tapes during a restore +operation. For example, it can make sense to append incremental dumps +of a volume set together in a single dump set. +

All the records for a dump set are indexed together in the Backup Database +based on the initial dump (for more on the Backup Database, see The Backup Database and Backup Server Process). To delete the database record of an appended dump, +you must delete the initial dump record, and doing so deletes the records for +all dumps in the dump set. Similarly, you cannot recycle just one tape +in a dump set without deleting the database records of all tapes in the dump +set. +

For instructions on creating an initial dump, see Backing Up Data, and to learn how to append dumps, see Appending Dumps to an Existing Dump Set. +

Dump Hierarchies, Dump Levels and Expiration Dates

+ + + + + + +

A dump hierarchy is a logical structure that defines the +relationship between full and incremental dumps; that is, it defines +which dump serves as the parent for an incremental dump. Each +individual component of a hierarchy is a dump level. When +you create a dump by issuing the backup dump command, you specify a +volume set name and a dump level name. The Backup System uses the dump +level to determine whether the dump is full or incremental, and if +incremental, which dump level to use as the parent. +

You can associate an expiration date with a dump level, to +define when a dump created at that level expires. The Backup System +refuses to overwrite a tape until all dumps in the dump set to which the tape +belongs have expired, so assigning expiration dates automatically determines +how you recycle tapes. You can define an expiration date either in +absolute terms (for example, 13 January 2000) or relative terms (for example, +30 days from when the dump is created). You can also change the +expiration date associated with a dump level (but not with an actual dump that +has already been created at that level). +

For instructions on creating dump hierarchies, assigning expiration dates, +and establishing a tape recycling schedule, see Defining and Displaying the Dump Hierarchy. + + + + + + +

Dump Names and Tape Names

When you create a dump, the Backup System creates a Backup +Database record for it, assigning a name comprising the volume set name and +the last element in the dump level pathname: +

   volume_set_name.dump_level_name
+

For example, a dump of the volume set user at the dump level +/sunday/friday is called user.friday. The +Backup System also assigns a unique dump ID number to the dump to +distinguish it from other dumps with the same name that possibly exist. +

The Backup System assigns a similar AFS tape name to each tape +that contains a dump set, reflecting the volume set and dump level of the dump +set's initial dump, plus a numerical index of the tape's position in +the dump set, and a unique dump ID number: +

   volume_set_name.dump_level_name.tape_index (dump ID)
+

For example, the second tape in a dump set whose initial dump is of the +volume set uservol at the dump level /sunday/friday has +AFS tape name like uservol.friday.2 +(914382400). +

In addition to its AFS tape name, a tape can have an optional +permanent name that you assign. Unlike the AFS tape name, +the permanent name does not have to indicate the volume set and dump level of +the initial (or any other) dump, and so does not change depending on the +contents of the tape. The Backup System does not require a certain +format for permanent names, so you need to make sure that each tape's +name is unique. If a tape has a permanent name, the Backup System uses +it rather than the AFS tape name when referring to the tape in prompts and the +output from most backup commands, but still tracks the AFS tape +name internally. +

Tape Labels, Dump Labels, and EOF Markers

+ + + + +

Every tape used in the Backup System has a magnetic label at the beginning +that records the tape's name, capacity, and other information. You +can use the backup labeltape command to write a label, or the +backup dump command creates one automatically if you use an +unlabeled tape. The label records the following information: +

The tape's permanent name, which you can assign by using the +-pname argument to the backup labeltape command. +It can be any string of up to 32 characters. If you do not assign a +permanent name, the Backup System records the value <NULL> when +you use the backup labeltape command to assign an AFS tape name, or +when you use the backup dump command to write a dump to the +tape. +
The tape's AFS tape name, which can be one of three types +of values: +
- A name that reflects the volume set and dump level of the dump set's +initial dump and the tape's place in the sequence of tapes for the dump +set, as described in Dump Names and Tape Names. If the tape does not have a permanent name, you can +assign the AFS tape name by using the -name argument to the +backup labeltape command. +
- The value <NULL>, which results when you assign a permanent +name, or provide no value for the backup labeltape command's +-name argument. +
- No AFS tape name at all, indicating that you have never labeled the tape +or written a dump to it. +
+
If a tape does not already have an actual AFS tape name when you write a +dump to it, the Backup System constructs and records the appropriate AFS tape +name. If the tape does have an AFS tape name and you are writing an +initial dump, then the name must correctly reflect the dump's volume set +and dump level. +
The capacity, or size, of the tape, followed by a letter that +indicates the unit of measure (k or K for kilobytes, +m or M for megabytes, g or G for +gigabytes, or t or T for terabytes). The +tape's manufacturer determines the tape's capacity. For +further discussion of how the Backup System uses the value in the capacity +field, see Configuring the tapeconfig File. +

For information about labeling tapes, see Writing and Reading Tape Labels. +

In addition to the tape label, the Backup System writes a dump +label on the tape for every appended dump (the tape label and dump label +are the same for the initial dump). A dump label records the following +information: +

The name of the tape containing the dump +
The date and time that the dump operation began +
The cell to which the volumes in the dump belong +
The dump's size in kilobytes +
The dump's dump level +
The dump's dump ID +

The Backup System writes a filemark (also called an End-of-File +or EOF marker) between the data from each volume in a dump. The tape +device's manufacturer determines the filemark size, which is typically +between 2 KB and 2 MB; in general, the larger the usual capacity of the +tapes that the device uses, the larger the filemark size. If a dump +contains a small amount of data from each of a large number of volumes, as +incremental dumps often do, then the filemark size can significantly affect +how much volume data fits on the tape. To enable the Backup System to +factor in filemark size as it writes a dump, you can record the filemark size +in a configuration file; see Configuring the tapeconfig File. +

Tape Coordinator Machines, Port Offsets, and Backup Data Files

+ + + + +

A Tape Coordinator machine is a machine that drives one or more +attached tape devices used for backup operations. It must run the AFS +client software (the Cache Manager) but reside in a physically secure location +to prevent unauthorized access to its console. Before backup operations +can run on a Tape Coordinator machine, each tape device on the machine must be +registered in the Backup Database, and certain files and directories must +exist on the machine's local disk; for instructions, see To configure a Tape Coordinator machine. +

Each tape device on a Tape Coordinator machine listens for backup requests +on a different UNIX port. You pick the port indirectly by assigning a +port offset number to the tape device. The Backup System +sets the device's actual port by adding the port offset to a base port +number that it determines internally. For instructions on assigning +port offset numbers, see Configuring the tapeconfig File. +

For a tape device to perform backup operations, a Backup Tape Coordinator +(butc) process dedicated to the device must be running actively on +the Tape Coordinator machine. You then direct backup requests to the +device's Tape Coordinator by specifying its port offset number with the +-portoffset argument to the backup command. +

In addition to writing backup data to tape, you can direct it to a +backup data file on the local disk of a Tape Coordinator +machine. You can then to transfer the data to a data-archiving system, +such as a hierarchical storage management (HSM) system, that you use in +conjunction with AFS and the Backup System. A backup data file has a +port offset like a tape device. For instructions on configuring backup +data files, see Dumping Data to a Backup Data File. +

The Backup Database and Backup Server Process

+ + +

The Backup Database is a replicated administrative database +maintained by the Backup Server process on the cell's database +server machines. Like the other AFS database server processes, the +Backup Server uses the Ubik utility to keep the various copies of the database +synchronized (for a discussion of Ubik, see Replicating the AFS Administrative Databases). +

The Backup Database records the following information: +

The Tape Coordinator machine's hostname and the port offset number +for each tape device used for backup operations +
The dump hierarchy, which consists of its component dump levels and their +associated expiration dates +
The volume sets and their component volume entries +
A record for each dump, which includes the name of each tape it appears +on, a list of the volumes from which data is included, the dump level, the +expiration date, and the dump ID of the initial dump with which the dump is +associated +
A record for each tape that houses dumped data +

Interfaces to the Backup System

The backup suite of commands is the administrative interface +to the Backup System. You can issue the commands in a command shell (or +invoke them in a shell script) on any AFS client or server machine from which +you can access the backup binary. In the conventional +configuration, the binary resides on the local disk. +

The backup command suite provides an interactive +mode, in which you can issue multiple commands over a persistent +connection to the Backup Server and the Volume Location (VL) Server. +Interactive mode has several convenient features, including the +following: +

You need to type only the operation code, omitting the initial +backup string. +
If you assume another AFS identity or specify a foreign cell as you enter +interactive mode, it applies to all subsequent commands. +
You do not need to enclose shell metacharacters in double quotes. +
You can track current and pending operations with the (backup) +jobs command, which is available only in this mode. +
You can cancel current and pending operations with the (backup) +kill command, which is available only in this mode. +

Before issuing a command that requires reading or writing a tape (or backup +data file), you must also open a connection to the Tape Coordinator machine +that is attached to the relevant tape device (or that has the backup data file +on its local disk), and issue the butc command to initialize the +Tape Coordinator process. The process must continue to run and the +connection remain open as long as you need to use the tape device or file for +backup operations. +

For further discussion and instructions, see Using the Backup System's Interfaces. +

Overview of Backup System Configuration

+ +

Before you can use the Backup System to back up and restore data, you must +configure several of its basic components. The indicated sections of +this chapter explain how to perform the following configuration tasks: +

Determining a tape's capacity and a tape device's filemark size, +and recording them in the /usr/afs/backup/tapeconfig file (see Configuring the tapeconfig File) +
Determining how to grant administrative privilege to backup operators (see +Granting Administrative Privilege to Backup Operators) +
Configuring Tape Coordinator machines, tape devices, and backup data files +(see Configuring Tape Coordinator Machines and Tape Devices) +
Defining volume sets and volume entries (see Defining and Displaying Volume Sets and Volume Entries) +
Defining dump levels to create a dump hierarchy (see Defining and Displaying the Dump Hierarchy) +
Labeling tapes (see Writing and Reading Tape Labels) +
Creating a device configuration file to automate the backup process (see Automating and Increasing the Efficiency of the Backup Process) +

If you have already configured all of the components required for +performing a backup dump or restore operation, you can proceed to the +instructions in Backing Up Data and Restoring and Recovering Data. +

Configuring the tapeconfig File

+ + + + + +

Several factors interact to determine how much data the Tape Coordinator +can fit on a tape: +

The tape's capacity (size), as set by the tape manufacturer. +
The tape device's filemark size, as set by the tape device's +manufacturer. Recall from Tape Labels, Dump Labels, and EOF Markers that the Tape Coordinator writes a filemark between the data +from each volume in a dump. If a dump contains a small amount of data +from each of a large number of volumes, as incremental dumps often do, then +the filemark size can significantly affect how much volume data fits on the +tape. +
Whether or not you use the tape device's compression mode. +

(The amount of data that can fit in a backup data file is determined by +amount of space available on the partition, and the operating system's +maximum file size. The Tape Coordinator does not write filemarks when +writing to a backup data file. For further information about +configuring a Tape Coordinator to write to a backup data file, see Dumping Data to a Backup Data File.) +

As the Tape Coordinator (butc) process initializes, it reads the +/usr/afs/backup/tapeconfig file on its local disk to learn the tape +capacity and filemark size (for a tape device) or the file size (for a backup +data file) to use for dump operations. When you begin a dump operation, +the Tape Coordinator also reads the tape or backup data file's label to +see if you have recorded a different tape capacity or file size. If you +have, the value on the label overrides the default value from the +tapeconfig file. +

As the Tape Coordinator writes data to a tape during a dump operation, it +uses the capacity and filemark information to track how much tape it has used +and how much remains before the physical end-of-tape (EOT). Shortly +before reaching EOT, the Tape Coordinator stops writing and requests a new +tape. Similarly, it uses a backup data file's size to know when it +is about to exhaust the space in the file. If the Tape Coordinator +reaches the EOT unexpectedly, it recovers by obtaining a new tape and writing +to it the entire contents of the volume it was writing when it reached +EOT. The interrupted volume remains on the first tape, but is never +used. +

Many tape devices use tapes that can accommodate multiple gigabytes, or +even multiple terabytes, of backup data, especially if you use the +device's compression mode. When writing to such devices and tapes, +allowing the Tape Coordinator to hit the EOT unexpectedly is generally +recommended. The devices write data so quickly that it usually does not +take much extra time to rewrite the interrupted volume on the new tape. +Similarly, they compress data so well that the data abandoned on the first +tape from the interrupted volume does not constitute a waste of much +tape. +

When writing to tapes that accommodate a smaller amount of data (say, less +than two GB), it is better to avoid having the Tape Coordinator hit EOT +unexpectedly. AFS supports volumes up to 2 GB in size, so an +interrupted volume can in fact take up most of the tape. For such +tapes, recording accurate values for tape capacity and filemark size, if +possible, helps to maximize both use of tape and the efficiency of dump +operations. The following discussion of the fields in the +tapeconfig file explains how to determine the appropriate +values. +

Use a text editor to create an entry in a Tape Coordinator's +tapeconfig file for each tape device or backup data file that it +uses. Each device or file's entry is on its own line and 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. Specify an integer value +followed by a letter that indicates units, with no intervening space. +The letter k or K indicates kilobytes, m or +M indicates megabytes, g or G indicates +gigabytes, and t or T indicates terabytes. If the +units letter is omitted, the default is kilobytes. +

To determine the capacity of a tape under two GB in size that you are going +to use in regular (noncompression) mode, you can either use the value that the +tape's manufacturer specifies on the tape's packaging or use the +fms command to calculate the capacity, as described later in this +section. To avoid having the Tape Coordinator reach the EOT +unexpectedly, it is best to record in the tapeconfig file or on the +label a capacity that is about 10% smaller than the actual capacity of the +tape. To calculate the appropriate value for a small tape used in +compression mode, one method is to multiply the tape capacity (as recorded by +the manufacturer) by the device's compression ratio. +

For tapes that hold multiple gigabytes or terabytes of data, or if using a +tape drive's compression mode, the recommended configuration is to record +a value quite a bit (for instance, two times) larger than the maximum amount +you believe can fit on the tape. It is not generally worthwhile to run +the fms command on large tapes, even in noncompression mode. +The command definitely does not yield accurate results in compression +mode. The Tape Coordinator is likely to reach the EOT unexpectedly, but +compression mode fits so much data on the tape that the data abandoned from an +interrupted volume does not represent much of the tape's capacity. +

For a backup data file, record a value slightly smaller than the amount of +space available on the partition, and definitely smaller than the operating +system's maximum file size. It is also best to limit the ability +of other processes to write to the partition, to prevent them from using up +the space in the partition. +

If this field is empty, 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 tape device's filemark size, which usually falls +between 2 KB and 2 MB. Use the same notation as for the +capacity field, but note that if you omit the units letter, the +default unit is bytes rather than kilobytes. +

For a tape device in regular (noncompression) mode, you can use the +fms command to determine filemark size, or use the value reported +by the device's manufacturer. To help the Tape Coordinator avoid +reaching EOT unexpectedly, increase the value by about 10% when recording it +in the tapeconfig file. +

The recommended value for a tape device in compression mode is 0 +(zero). The fms command does not yield accurate results in +compression mode, so you cannot use it to determine the filemark size. +

The recommended value for a backup data file is also 0 +(zero). The Tape Coordinator does not use filemarks when writing to a +file, but a value must appear in this field nevertheless if there is also a +value in the capacity field. +

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, but for suggestions on how to name a backup data file, see Dumping Data to a Backup Data File. +

port_offset +

Specifies the port offset number for a specific tape device or backup data +file. Each tape device listens for backup requests on a different UNIX +port. You pick the port indirectly by recording a value in this +field. The Backup System sets the device's actual port by adding +the port offset to a base port number that it determines internally. +

Legal 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 you do not +have to assign port offset numbers sequentially, and you can associate any +number of them with a single machine or even tape device. For example, +if you plan to use a device in both compression and noncompression mode, +assign it two different port offsets with appropriate tape capacity and +filemark values for the different modes. +

Assign port offset 0 (zero) to the Tape Coordinator for the tape +device or backup data file that you use most often for backup operations; +doing so enables you to omit the -portoffset argument from the +largest possible number of backup commands. +

The following example tapeconfig file includes entries for two +tape devices, /dev/rmt0h and /dev/rmt1h. Each one +uses tapes with a capacity of 2 GB and has a filemark size of 1 MB. +Their port offset numbers are 0 and 1. +

   2g 1m /dev/rmt0h 0
+   2G 1M /dev/rmt1h 1
+

The fms command reports the capacity of the tape you have +inserted and the tape device's filemark size, both on the standard output +stream (stdout) and in its fms.log file, which it writes in +the current working directory. The command interpreter must write data +to the entire tape, so running the command can take from several hours to more +than a day, depending on the size of the tape. +

To run the fms command on a noncompressing tape device

+ + + + + +

If an fms.log file does not already exist in the current +directory, verify that you can insert and write to files in the current +directory. If the log file already exists, you must be able to write to +the file. +
Insert a tape into the drive. Running the command completely +overwrites the tape, so use a blank tape or one that you want to +recycle. +
Issue the fms command. +
```
   % fms <tape special file>
+
```
+
where +
+
fms +
Must be typed in full. +
tape special file +
Specifies the tape device's UNIX device name, such as +/dev/rmt0h. +
+

The following example output reports that the tape in the device with +device name /dev/rmt0h has a capacity of 2136604672 bytes (about 2 +GB), and that the device's filemark size is 1910205 bytes (close to 2 +MB). +

   % fms /dev/rmt0h
+   wrote block: 130408
+   Finished data capacity test - rewinding
+   wrote 1109 blocks, 1109 file marks
+   Finished file mark test
+   Tape capacity is 2136604672 bytes
+   File marks are 1910205 bytes
+

Granting Administrative Privilege to Backup Operators

Each person who issues the backup and +butc commands in your cell must be listed in the +/usr/afs/etc/UserList file on every database server machine that +stores the Backup Database and Volume Location Database (VLDB), and every +machine that houses a volume included in a volume set. By convention, +the UserList file is the same on every server machine in the +cell; the instructions in this document assume that your cell is +configured in this way. To edit the UserList file, use the +bos adduser and bos removeuser commands as described in Administering the UserList File. +

In addition to being listed in the UserList file, backup +operators who issue the butc command must be able to write to the +files stored in each Tape Coordinator machine's local +/usr/afs/backup directory, which are protected by UNIX mode +bits. Before configuring your cell's first Tape Coordinator +machine, decide which local user and group to designate as the owner of the +directory and the files in it. Among the possible ownership options are +the following: +

The local superuser root. With this option, the issuer +of the butc command must log onto the local file system as the +local superuser root. If the Tape Coordinator is also a +server machine, the -localauth flag is used on the butc +command to construct a server ticket from the local +/usr/afs/etc/KeyFile file. On non-server machine, the issuer +must issue the klog command to authenticate as an AFS administrator +while logged in as root. +
A single AFS administrator. Logging in and authenticating are a +single step if an AFS-modified login utility is used. The administrator +is the only user who can start the Tape Coordinator. +
An administrative account for which several operators know the +password. This allows them all to start the Tape Coordinator. +

Another option is to define a group in the local group file +(/etc/group or equivalent) to which all backup operators +belong. Then turn on the w mode bit (write +permission) in the group mode bits rather than the user mode bits of the +/usr/afs/backup directory and files in it. An advantage over +the methods listed previously is that each operator can retain an individual +administrative account for finer granularity in auditing. +

For instructions on implementing your choice of protection methods, see Configuring Tape Coordinator Machines and Tape Devices. +

Configuring Tape Coordinator Machines and Tape Devices

+ + + + +

This section explains how to configure a machine as a Tape Coordinator +machine, and how to configure or remove the Tape Coordinator associated with a +single tape device or backup data file. +
Note: When configuring a tape device attached to an AIX system, you must set the +device's tape block size to 0 (zero) to indicate variable +block size. If you do not, it is possible that devices attached to +machines of other system types cannot read the tapes made on the AIX +system. Use the AIX smit program to verify or change the +value of the tape block size for a tape device, as instructed in Sep 3. +
+

To configure a Tape Coordinator machine

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Install one or more tape devices on the Tape Coordinator +machine according to the manufacturer's instructions. The Backup +System can track a maximum of 58,511 tape devices or backup data files per +cell. +
If the Tape Coordinator machine is an AIX system, issue the following +command to change the tape device's tape block size to 0 +(zero), which indicates variable block size. Repeat for each tape +device. +
```
   # chdev -l 'device_name' -a block_size='0'
+
```
+
where device_name is the tape device's device name (for +example, /dev/rmt0h). +
Verify that the binary files for the backup, butc, +and fms commands are available on the local disk. If the +machine is an AFS client, the conventional location is the +/usr/afsws/etc directory. +
```
   # ls /usr/afsws/etc
+
```
+
Create the /usr/afs directory. (If the Tape Coordinator +machine is also configured as a file server machine, this directory already +exists.) Then create the /usr/afs/backup directory. +
```
   # mkdir /usr/afs
+   # mkdir /usr/afs/backup
+
```
+
Use a text editor to create the /usr/afs/backup/tapeconfig +file. Include a single line for each tape device or backup data file, +specifying the following information in the indicated order. For syntax +details and suggestions on the values to use in each field, see Configuring the tapeconfig File. +
- The capacity of tapes to be used in the device, or the size of the backup +data file +
- The device's filemark size +
- The device's device name, starting with the string /dev/ +
- The device's port offset number +
+ + + + +

Decide which user and group are to own the /usr/afs/backup +directory and /usr/afs/backup/tapeconfig file, based on the +suggestions in Granting Administrative Privilege to Backup Operators. Correct the UNIX mode bits on the directory and +file, if necessary. +

   # chown admin_owner /usr/afs/backup
+   # chown admin_owner /usr/afs/backup/tapeconfig
+   # chgrp admin_group /usr/afs/backup
+   # chgrp admin_group /usr/afs/backup/tapeconfig
+   # chmod 774 /usr/afs/backup
+   # chmod 664 /usr/afs/backup/tapeconfig
+

+ + + + +

Issue the backup addhost command to create +a Tape Coordinator entry in the Backup Database. Repeat the command for +each Tape Coordinator. +
```
   # backup addhost <tape machine name> [<TC port offset>]
+
```
+
where +
+
addh +
Is the shortest acceptable abbreviation of addhost. +
tape machine name +
Specifies the Tape Coordinator machine's fully qualified +hostname. +
TC port offset +
Specifies the tape device's port offset number. Provide the +same value as you specified for the device in the tapeconfig +file. You must provide this argument unless the default value of 0 +(zero) is appropriate. +
+

To configure an additional Tape Coordinator on an existing Tape Coordinator machine

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Install the tape device on the Tape Coordinator machine according to the +manufacturer's instructions. +
If the Tape Coordinator machine is an AIX system, issue the following +command to change the tape device's tape block size to 0 +(zero), which indicates variable block size. +
```
   # chdev -l 'device_name' -a block_size='0'
+
```
+
Choose the port offset number to assign to the tape device. If +necessary, use the backup listhosts command to display the port +offset numbers that are already used; for a discussion of the output, see +To display the list of configured Tape Coordinators. +
```
   # backup listhosts
+
```
+
where listh is the shortest acceptable abbreviation of +listhosts. +
Use a text editor to add one or more entries for the device to the +/usr/afs/backup/tapeconfig file. Specify the following +information in the indicated order. For syntax details and suggestions +on the values to use in each field, see Configuring the tapeconfig File. +
- The capacity of tapes to be used in the device, or the size of the backup +data file +
- The device's filemark size +
- The device's device name, starting with the string /dev/ +
- The device's port offset number +
+
Issue the backup addhost command to create an entry in the +Backup Database for the Tape Coordinator. For complete syntax, see Step +8 in To configure a Tape Coordinator machine. +
```
   # backup addhost <tape machine name> [<TC port offset>]
+
```
+

+ + + + +

To unconfigure a Tape Coordinator

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Using a text editor, remove each of the Tape Coordinator's entries +from the /usr/afs/backup/tapeconfig file. +
Issue the backup delhost command to delete the Tape +Coordinator's Backup Database entry. +
```
   % backup delhost <tape machine name> [<TC port offset>]
+
```
+
where +
+
delh +
Is the shortest acceptable abbreviation of delhost. +
tape machine name +
Is the complete Internet host name of the Tape Coordinator machine. +
TC port offset +
Is the same port offset number removed from the tapeconfig +file. You must provide this argument unless the default value of +0 (zero) is appropriate. +
+

+ + + + +

To display the list of configured Tape Coordinators

Issue the backup listhosts command to list the Tape +Coordinators and port offset numbers currently configured in the Backup +Database. +
```
   % backup listhosts
+
```
+
where +
+
listh +
Is the shortest acceptable abbreviation of listhosts. +
+

The output lists each Tape Coordinator machine and the port offset numbers +currently allocated to it in the Backup Database. The appearance of a +port offset number does not imply that the associated Tape Coordinator is +actually running. Machine names appear in the format in which they were +specified with the backup addhost command. +

The following example output lists the Tape Coordinators currently defined +in the Backup Database of the ABC Corporation cell: +

   % backup listhosts
+   Tape hosts:
+       Host backup1.abc.com, port offset 0
+       Host backup1.abc.com, port offset 2
+       Host backup2.abc.com, port offset 1
+       Host backup2.abc.com, port offset 3
+

Defining and Displaying Volume Sets and Volume Entries

The Backup System handles data at the level of volumes +rather than individual files. You must define groups of volumes called +volume sets before performing backup operations, by using the +backup addvolset command. A volume set name can be up to 31 +characters long and can include any character other than the period +(.), but avoid using metacharacters that have special +meanings to the shell. +

After creating a volume set, use the backup addvolentry command +to place one or more volume entries in it. They define the +volumes that belong to it in terms of their location (file server machine and +partition) and name. Use the command's required -server +argument to designate the file server machine that houses the volumes of +interest and its required -partition argument to designate the +partition. Two types of values are acceptable: +

The fully qualified hostname of one machine or full name of one partition +(such as /vicepm) +
The regular expression .* (period and asterisk), which +matches every machine name or partition name in the VLDB +

For the volume name (the required -volume argument), specify a +combination of alphanumeric characters and one or more metacharacters to +specify part or all of the volume name with a wildcard. You can use any +of the following metacharacters in the volume name field: + + +

. +: 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. You can combine this expression with the +asterisk. +
^ +: The caret, when used as the first character in a square-bracketed set, +designates a match with any single character other than the characters that +follow it; for example, [^a] matches any single character +except lowercase a. You can combine this expression 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, +\* matches a single asterisk, and \\ matches a single +backslash. You can combine such expressions with the asterisk (for +example, \.* matches any number of periods). +

Perhaps the most common regular 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 +regular expression in the file server and partition fields of a volume +entry. In the volume name field, it can stand alone (in which case it +matches every volume listed in the VLDB), or can combine with alphanumeric +characters. For example, the string +user.*\.backup matches any volume name that begins +with the string user and ends with +.backup. +

Issuing the backup addvolentry command in interactive mode is +simplest. If you issue it at the shell prompt, you must surround any +string that includes a regular expression with double quotes (" ") +so that the shell passes them uninterpreted to the backup command +interpreter rather than resolving them. +

To define various combinations of volumes, provide the following types of +values for the backup addvolentry command's three +arguments. The list uses the notation appropriate for interactive +mode; if you issue the command at the shell prompt instead, place double +quotes around any string that includes a regular expression. To create +a volume entry that includes: +

All volumes listed in the VLDB, use the regular expression +.* for all three arguments (-server .* +-partition .* -volume .*) +
Every volume on a specific file server machine, specify its fully +qualified hostname as the -server argument and use the regular +expression .* for the -partition and +-volume arguments (for example: -server +fs1.abc.com -partition .* -volume .*) +
All volumes that reside on a partition with the same name on various file +server machines, specify the complete partition name as the +-partition argument and use the regular expression +.* for the -server and -volume +arguments (for example: -server .* -partition /vicepd +-volume .*) +
Every volume with a common string in its name, use the regular expression +.* for the -server and -partition +arguments, and provide a combination of alphanumeric characters and +metacharacters as the -volume argument (for example: +-server .* -partition .* -volume +.*\.backup includes all volumes whose names end in the +string .backup). +
All volumes on one partition, specify the machine's fully qualified +hostname as the -server argument and the full partition name as the +-partition argument, and use the regular expression +.* for the -volume argument (for example: +-server fs2.abc.com -partition /vicepb -volume +.*). +
A single volume, specify its complete name as the -volume +argument. To bypass the potentially time-consuming search through the +VLDB for matching entries, you can specify an actual machine and partition +name for the -server and -partition arguments +respectively. However, if it is possible that you need to move the +volume in future, it is best to use the regular expression +.* for the machine and partition name. +

As you create volume sets, define groups of volumes you want to dump to the +same tape at the same time (for example, weekly or daily) and in the same +manner (fully or incrementally). In general, a volume set that includes +volumes with similar contents (as indicated by similar names) is more useful +than one that includes volumes that share a common location, especially if you +often move volumes for load-balancing or space reasons. Most often, +then, it is appropriate to use the regular expression .* +(period followed by a backslash) for the -server and +-partition arguments to the backup addvolentry +command. +

It is generally more efficient to include a limited number of volumes in a +volume entry. Dumps of a volume set that includes a large number of +volume can take a long time to complete, increasing the possibility that the +operation fails due to a service interruption or outage. +

To remove a volume entry from a volume set, use the backup +delvolentry command. To remove a volume set and all of its +component volume entries from the Backup Database, use the backup +delvolset command. To display the volume entries in a volume set, +use the backup listvolsets command. +

By default, a Backup Database record is created for the new 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 (for further discussion, see Using the backup volsetrestore Command). To create a temporary volume set, +include the -temporary flag to the backup addvolset +command. 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). You can use the backup delvolset command to delete +a temporary volume set before the interactive session ends, if you wish, but +as noted it is automatically deleted when you end the session. 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 you are not creating any Backup Database records. + + + + +

To create a volume set

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
(Optional) Issue the backup command to enter +interactive mode. If you are going to define volume entries right away +with the backup addvolentry command, this eliminates the need to +surround metacharacter expressions with double quotes. You must enter +interactive mode if creating a temporary volume set. +
```
   % backup
+
```
+
Issue the (backup) addvolset command to create the volume +set. You must then issue the (backup) addvolentry command to +define volume entries in it. +
```
   backup>  addvolset <volume set name> [-temporary]
+
```
+
where +
+
addvols +
Is the shortest acceptable abbreviation of addvolset. +
volume set name +
Names the volume set. The name can include no more than 31 +characters, cannot include periods, and must be unique within the Backup +Database. (A temporary volume set can have the same name as an existing +permanent volume set, but this is not recommended because of the confusion it +can cause.) +
-temporary +
Creates a temporary volume set, which exists only during the current +interactive session. +
+

+ + + + +

To add a volume entry to a volume set

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
(Optional) Issue the backup command to enter +interactive mode if you have not already. This makes it simpler to use +metacharacter expressions, because you do not need to surround them with +double quotes. If you are adding entries to a temporary volume set, you +must already have entered interactive mode before creating the volume +set. +
```
   % backup
+
```
+
Issue the (backup) addvolentry command to define volume entries +in an existing volume set. The Backup System assigns each volume entry +an index within the volume set, starting with 1 (one). +
```
   backup> addvolentry  -name <volume set name>  \
+                        -server <machine name>  \
+                        -partition <partition name>  \
+                        -volumes <volume name (regular expression)>
+
```
+
where +
+
addvole +
Is the shortest acceptable abbreviation of addvolentry. +
-name +
Names the volume set to which to add the volume entry. It 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, +identifying them by name. This argument can include a combination of +alphanumeric characters and one or more of the metacharacter expressions +discussed in the introductory material in this section. +
+

+ + + + + + +

To display volume sets and volume entries

Issue the backup listvolsets command to display the volume +entries in a specific volume set or all of them. If you are displaying +a temporary volume set, you must still be in the interactive session in which +you created it. +
```
   % backup listvolsets [<volume set name>]
+
```
+
where +
+
listv +
Is the shortest acceptable abbreviation of listvolsets. +
volume set name +
Names the volume set to display. Omit this argument to display all +defined volume sets. +
+
The output from the command uses the wildcard notation used when the volume +entries were created. The string (temporary) marks a +temporary volume set. The following example displays all three of the +volume sets defined in a cell's Backup Database, plus a temporary volume +set pat+jones created during the current interactive session: +
+
```
   backup> listv
+   Volume set pat+jones (temporary):
+     Entry 1: server fs1.abc.com, partition /vicepe, volumes: user.pat.backup
+     Entry 2: server fs5.abc.com, partition /viceph, volumes: user.jones.backup
+   Volume set user:
+     Entry 1: server .*, partition .*, volumes: user.*\.backup
+   Volume set sun:
+     Entry 1: server .*, partition .*, volumes: sun4x_55\..*
+     Entry 2: server .*, partition .*, volumes: sun4x_56\..*
+   Volume set rs:
+     Entry 1: server .*, partition .*, volumes: rs_aix42\..*
+
```
+

+ + + + +

To delete a volume set

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the backup delvolset command to delete one or more volume +sets and all of the component volume entries in them. If you are +deleting a temporary volume set, you must still be in the interactive session +in which you created it. +
```
   % backup delvolset <volume set name>⁺
+
```
+
where +
+
delvols +
Is the shortest acceptable abbreviation of delvolset. +
volume set name +
Names each volume set to delete. +
+

+ + + + + +

To delete a volume entry from a volume set

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the backup command to enter interactive mode. +
```
   % backup
+
```
+
If the volume set includes more than one volume entry, issue the +(backup) listvolsets command to display the index number associated +with each one (if there is only one volume entry, its index is 1). For +a more detailed description of the command's output, see To display volume sets and volume entries. +
```
   backup> listvolsets <volume set name>
+
```
+
where +
+
listv +
Is the shortest acceptable abbreviation of listvolsets. +
volume set name +
Names the volume set for which to display volume entries. +
+
Issue the (backup) delvolentry command to delete the volume +entry. +
```
   backup> delvolentry <volume set name>  <volume entry index>
+
```
+
where +
+
delvole +
Is the shortest acceptable abbreviation of delvolentry. +
volume set name +
Names the volume set from which to delete a volume entry. +
volume entry index +
Specifies the index number of the volume entry to delete. +
+

Defining and Displaying the Dump Hierarchy

+ + +

A dump hierarchy is a logical structure in the Backup Database that defines +the relationship between full and incremental dumps; that is, it defines +which dump serves as the parent for an incremental dump. Each +individual component of a hierarchy is a dump level. +

As you define dump levels with the backup adddump command, keep +the following rules and suggestions in mind: +

Each full dump level is the top level of a hierarchy. You can +create as many hierarchies as you need to dump different volume sets on +different schedules. +
The name of a full dump level consists of an initial slash (/), +followed by a string of up to 28 alphanumeric characters. +
The name of an incremental dump level resembles a pathname, starting with +the name of a full dump level, then the first incremental level, and so on, +down to the final incremental level. Precede each level name with a +slash to separate it from the preceding level. Like the full level, +each component level in the name can have up to 28 alphanumeric characters, +not including the slash. +
A hierarchy can have any have any number of levels, but the maximum length +of a complete dump level name is 256 characters, including the slashes. +
Before defining a given incremental level, you must define all of the +levels above it in the hierarchy. +
Do not use the period (.) in dump level names. +The Backup System uses the period as the separator between a dump's +volume set name and dump level name when it creates the dump name and AFS tape +name. Any other alphanumeric and punctuation characters are allowed, +but it is best to avoid metacharacters. If you include a metacharacter, +you must precede it with a backslash (\) or surround the entire +dump level name with double quotes (" "). +
Naming dump levels for days or other actual time points reminds you when +to perform dumps, and makes it easier to track the relationship between dumps +performed at different levels. However, the names have no meaning to +the Backup System: it does not automatically create dumps according to +the names, and does not prevent you from, for example, using the +/sunday level when creating a dump on a Tuesday. +
It is best not to use the same name for more than one component level in a +hierarchy, because it means the resulting dump name no longer indicates which +level was used. For example, if you name a dump level +/full/incr/incr, then the dump name and AFS tape name that result +from dumping a volume set at the first incremental level +(/full/incr) look the same as the names that result from dumping at +the second incremental level (/full/incr/incr). +
Individual levels in different hierarchies can have the same name, but the +complete pathnames must be unique. For example, +/sunday1/monday and /sunday2/monday share the same name +at the final level, but are unique because they have different names at the +full level (belong to different hierarchies). However, using the same +name in multiple hierarchies means that dump and AFS tape names do not +unambiguously indicate which hierarchy was used. +

The following example shows three hierarchies. Each begins with a +full dump at the top: sunday1 for the first hierarchy, +sunday2 for the second hierarchy, and sunday_bin for the +third hierarchy. In all three hierarchies, each of the other dump +levels is an incremental level. +

   /sunday1
+           /monday
+           /tuesday
+           /wednesday
+           /thursday
+           /friday
+   /sunday2
+           /monday
+                  /tuesday
+                          /wednesday
+                                    /thursday
+                                             /friday
+    /sunday_bin
+               /monday
+                      /wednesday
+                                /friday
+

In the first hierarchy, each incremental dump level refers to the full +level /sunday1 as its parent. When (for example) you dump a +volume set at the /sunday1/wednesday level, it includes data that +has changed since the volume set was dumped at the /sunday1 +level. +

In contrast, each incremental dump level in the second hierarchy refers to +the immediately preceding dump level as its parent. When you dump a +volume set at the corresponding level in the second hierarchy +(/sunday2/monday/tuesday/wednesday), the dump includes only data +that has changed since the volume set was dumped at the +/sunday2/monday/tuesday level (presumably the day before). +Assuming you create dumps on the indicated days, an incremental dump made +using this hierarchy contains less data than an incremental dump made at the +corresponding level in the first hierarchy. +

The third hierarchy is more appropriate for dumping volumes for which a +daily backup is excessive because the data does not change often (for example, +system binaries). +

Creating a Tape Recycling Schedule

+ + + + + + + + +

If your cell is like most cells, you have a limited amount of room for +storing backup tapes and a limited budget for new tapes. The easiest +solution is to recycle tapes by overwriting them when you no longer need the +backup data on them. The Backup System helps you implement a recycling +schedule by enabling you to associate an expiration date with each dump +level. The expiration date defines when a dump created at that level +expires. Until that time the Backup System refuses to overwrite a tape +that contains the dump. Thus, assigning expiration dates automatically +determines how you recycle tapes. +

When designing a tape-recycling schedule, you must decide how far in the +past and to what level of precision you want to guarantee access to backed up +data. For instance, if you decide to guarantee that you can restore a +user's home volume to its state on any given day in the last two weeks, +you cannot recycle the tape that contains a given daily dump for at least two +weeks after you create it. Similarly, if you decide to guarantee that +you can restore home volumes to their state at the beginning of any given week +in the last month, you cannot recycle the tapes in a dump set containing a +weekly dump for at least four weeks. The following example dump +hierarchy implements this recycling schedule by setting the expiration date +for each daily incremental dump to 13 days and the expiration date of the +weekly full dumps to 27 days. +

The tapes used to store dumps created at the daily incremental levels in +the /sunday1 hierarchy expire just in time to be recycled for daily +dumps in the /sunday3 hierarchy (and vice versa), and there is a +similar relationship between the /sunday2 and /sunday4 +hierarchies. Similarly, the tape that houses a full dump at the +/sunday1 level expires just in time to be used for a full dump on +the first Sunday of the following month. +

   
+   /sunday1   expires in 27d
+           /monday1  expires in 13d
+           /tuesday1  expires in 13d
+           /wednesday1  expires in 13d
+           /thursday1  expires in 13d
+           /friday1  expires in 13d
+   /sunday2   expires in 27d
+           /monday2  expires in 13d
+           /tuesday2  expires in 13d
+           /wednesday2  expires in 13d
+           /thursday2  expires in 13d
+           /friday2  expires in 13d
+   /sunday3   expires in 27d
+           /monday1  expires in 13d
+           /tuesday1  expires in 13d
+           /wednesday1  expires in 13d
+           /thursday1  expires in 13d
+           /friday1  expires in 13d
+   /sunday4   expires in 27d
+           /monday2  expires in 13d
+           /tuesday2  expires in 13d
+           /wednesday2  expires in 13d
+           /thursday2  expires in 13d
+           /friday2  expires in 13d
+

If you use appended dumps in your cell, keep in mind that all dumps in a +dump set are subject to the latest (furthest into the future) expiration date +associated with any of the constituent dumps. You cannot recycle any of +the tapes that contain a dump set until all of the dumps have reached their +expiration date. See also Appending Dumps to an Existing Dump Set. +

Most tape manufacturers recommend that you write to a tape a limited number +of times, and it is best not to exceed this limit when recycling tapes. +To help you track tape usage, the Backup System records a useCount +counter on the tape's label. It increments the counter each time +the tape's label is rewritten (each time you use the backup +labeltape or backup dump command). To display the +useCount counter, use the backup readlabel or +backup scantape command or include the -id and +-verbose options when you issue the backup dumpinfo +command. For instructions see Writing and Reading Tape Labels or Displaying Backup Dump Records. + + + + +

Archiving Tapes

+ + +

Even if you make extensive use of tape recycling, there is probably some +backup data that you need to archive for a long (or even an indefinite) period +of time. You can use the Backup System to archive data on a regular +schedule, and you can also choose to archive data on tapes that you previously +expected to recycle. +

If you want to archive data on a regular basis, you can create +date-specific dump levels in the dump hierarchy. For example, if you +decide to archive a full dump of all data in your cell at the beginning of +each quarter in the year 2000, you can define the following levels in the dump +hierarchy: +

   /1Q2000
+   /2Q2000
+   /3Q2000
+   /4Q2000
+

If you decide to archive data that is on tapes you previously planned to +recycle, you must gather all of the tapes that contain the relevant dumps, +both full and incremental. To avoid accidental erasure, it is best to +set the switch on the tapes that makes them read-only, before placing them in +your archive storage area. If the tapes also contain a large amount of +extraneous data that you do not want to archive, you can restore just the +relevant data into a new temporary volume, and back up that volume to the +smallest number of tapes possible. One reason to keep a dump set small +is to minimize the amount of irrelevant data in a dump set you end up needing +to archive. +

If you do not expect to restore archived data to the file system, you can +consider using the backup deletedump command to remove the +associated dump records from the Backup Database, which helps keep it to an +efficient size. If you ever need to restore the data, you can use the +-dbadd flag to the backup scantape command to reinsert +the dump records into the database. For instructions, see To scan the contents of a tape. +

Defining Expiration Dates

To associate an expiration date with a dump level as you +create it, use the -expires argument to the backup +adddump command. To change an existing dump level's +expiration date, use the -expires argument to the backup +setexp command. (Note that it is not possible to change the +expiration date of an actual dump that has already been created at that +level). With both commands, you can define an expiration date either in +absolute terms (for example, 13 January 2000) or relative terms (for example, +30 days from when the dump is created). +

To define an absolute expiration date, provide a value for the +-expires argument with the following format: +
```
   [at] mm/dd/yyyy [hh:MM]
+
```
+
where mm indicates the month, dd the day, and +yyyy the year when the dump expires. Valid values for the year +fall in the range 1970 through 2037 (the latest possible +date that the UNIX time representation can express is in early 2038). +If you provide a time, it must be in 24-hour format with hh the hours +and MM the minutes (for example, 21:50 is 9:50 +p.m.). If you omit the time, the default is 00:00 +hours (12:00 midnight) on the indicated date. +
To define a relative expiration date, provide a value for the +-expires argument with the following format: +
```
   [in] [yearsy] [monthsm] [daysd]
+
```
+
where each of years, months, and days is an +integer. Provide at least one of them together with the corresponding +units letter (y, m, or d respectively), with +no intervening space. If you provide more than one of the three, list +them in the indicated order. +
The Backup System calculates a dump's actual expiration date by adding +the indicated relative value to the start time of the dump operation. +For example, it assigns an expiration date 1 year, 6 months, and 2 days in the +future to a dump created at a dump level with associated expiration date +in 1y 6m 2d. +
To indicate that a dump backed up at the corresponding dump level never +expires, provide the value NEVER instead of a date and time. +To recycle tapes that contain dumps created at such a level, you must use the +backup readlabel command to overwrite the tape's label. +

If you omit the -expires argument to the backup +adddump command, then the expiration date is set to UNIX time zero +(00:00 hours on 1 January 1970). The Backup System considers +dumps created at such a dump level to expire at their creation time. If +no dumps in a dump set have an expiration date, then the Backup System does +not impose any restriction on recycling the tapes that contain the dump +set. If you need to prevent premature recycling of the tapes that +contain the dump set, you must use a manual tracking system. + + + + + + + + + +

To add a dump level to the dump hierarchy

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Optional. Issue the backup command to enter +interactive mode. +
```
   % backup
+
```
+

Issue the backup adddump command to define one or more dump +levels. If you are defining an incremental level, then all of the +parent levels that precede it in its pathname must either already exist or +precede it on the command line. +

   backup> adddump -dump <dump level name>⁺ [-expires <expiration date>⁺]
+

where +

addd +

Is the shortest acceptable abbreviation of adddump. +

-dump +

Names each dump level to added. If you specify more than one dump +level name, you must include the -dump switch. +

Provide the entire pathname of the dump level, preceding each level in the +pathname with a slash (/). Each component level can be up to +28 characters in length, and the pathname can include up to 256 characters +including the slashes. +

-expires +

Sets the expiration date associated with each dump level. Specify +either a relative or absolute expiration date, as described in Defining Expiration Dates, or omit this argument to assign no expiration date to the +dump levels. +

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. +

+ + + + + + +

To change a dump level's expiration date

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Optional. Issue the backup command to enter +interactive mode. +
```
   % backup
+
```
+

Issue the (backup) setexp command to change the expiration date +associated with one or more dump levels. +

   backup> setexp -dump <dump level name>⁺ [-expires <expiration date>⁺]
+

where +

se +

Is the shortest acceptable abbreviation of setexp. +

-dump +

Names each existing dump level for which to change the expiration +date. +

-expires +

Sets the expiration date associated with each dump level. Specify +either a relative or absolute expiration date, as described in Defining Expiration Dates; omit this argument to remove the expiration date +currently associated with each dump level. +

Note:

+ + + + + +

To delete a dump level from the dump hierarchy

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Optional. Issue the backup command to enter +interactive mode. +
```
   % backup
+
```
+
Issue the (backup) deldump command to delete the dump +level. Note that the command automatically removes all incremental dump +levels for which the specified level serves as parent, either directly or +indirectly. +
```
   backup> deldump <dump level name>
+
```
+
where +
+
deld +
Is the shortest acceptable abbreviation of deldump. +
dump level name +
Specifies the complete pathname of the dump level to delete. +
+

+ + + + + + +

To display the dump hierarchy

Issue the backup listdumps command to display the dump +hierarchy. +

   % backup listdumps
+

where listd is the shortest acceptable abbreviation of +listdumps. +

The output from this command displays the dump hierarchy, reporting the +expiration date associated with each dump level, as in the following +example. +

    % backup listdumps
+   /week1  expires in  27d
+         /tuesday  expires in  13d
+                 /thursday  expires in  13d
+         /sunday  expires in  13d
+                /tuesday expires in  13d
+                        /thursday expires in  13d
+   /week3  expires in  27d
+         /tuesday  expires in  13d
+                 /thursday  expires in  13d
+         /sunday  expires in  13d
+                /tuesday  expires in  13d
+                        /thursday  expires in  13d
+   sunday1   expires in  27d
+          /monday1  expires in  13d
+          /tuesday1  expires in  13d 
+          /wednesday1  expires in  13d
+          /thursday1  expires in  13d
+          /friday1  expires in  13d
+   sunday2   expires in  27d
+          /monday2  expires in  13d
+          /tuesday2  expires in  13d
+          /wednesday2  expires in  13d
+          /thursday2  expires in  13d
+          /friday2  expires in  13d
+   sunday3   expires in  27d
+          /monday1  expires in  13d
+          /tuesday1  expires in  13d 
+          /wednesday1  expires in  13d
+          /thursday1  expires in  13d
+          /friday1  expires in  13d
+   sunday4   expires in  27d
+          /monday2  expires in  13d
+          /tuesday2  expires in  13d
+          /wednesday2  expires in  13d
+          /thursday2  expires in  13d
+          /friday2  expires in  13d
+

Writing and Reading Tape Labels

+ + + + + + +

As described in Dump Names and Tape Names and Tape Labels, Dump Labels, and EOF Markers, you can assign either a permanent name or +an AFS tape name to a tape that you use in the Backup System. The names +are recorded on the tape's magnetic label, along with an indication of +the tape's capacity (size). +

You can assign either a permanent name or an AFS tape name, but not +both. In general, assigning permanent names rather than AFS tape names +simplifies the backup process, because the Backup System does not dictate the +format of permanent names. If a tape does not have a permanent name, +then by default the Backup System accepts only three strictly defined values +in the AFS tape name field, and refuses to write a dump to a tape with an +inappropriate AFS tape name. The acceptable values are a name that +matches the volume set and dump level of the initial dump, the value +<NULL>, and no value in the field at all. +

If a tape has a permanent name, the Backup System does not check the AFS +tape name, and as part of the dump operation constructs the appropriate AFS +tape name itself and records it on the label. This means that if you +assign a permanent name, the Backup System assigns an AFS tape name itself and +the tape has both types of name. In contrast, if a tape has an AFS tape +name but not a permanent name, you cannot assign a permanent name without +first erasing the AFS tape name. +

(You can also suppress the Backup System's check of a tape's AFS +tape name, even it does not have a permanent name, by assigning the value +NO to the NAME_CHECK instruction in the device +configuration file. See Eliminating the AFS Tape Name Check.) +

Because the Backup System accepts unlabeled tapes, you do not have to label +a tape before using it for the first time. After the first use, there +are a couple of cases in which you must relabel a tape in order to write a +dump to it: +

The tape does not have a permanent name, and the AFS tape name on it does +not match the new initial dump set you want to create (the volume set and dump +level names are different, or the index is incorrect). +
You want to recycle a tape before all of the dumps on it have +expired. The Backup System does not overwrite a tape with any unexpired +dumps. Keep in mind, though, that if you relabel the tape to making +recycling possible, you erase all the dump records for the tape from the +Backup Database, which makes it impossible to restore any data from the +tape. +

Note:

Labeling a tape that contains dump data makes it impossible to use that data +in a restore operation, because the labeling operation removes the dump's +records from the Backup Database. If you want to record a permanent +name on a tape label, you must do it before dumping any data to the +tape. +

Recording a Name on the Label

To write a permanent name on a tape's label, include the +-pname argument to specify a string of up to 32 characters. +Check that no other tape used with the Backup System in your cell already has +the permanent name you are assigning, because the Backup System does not +prevent you from assigning the same name to multiple tapes. The Backup +System overwrites the existing AFS tape name, if any, with the value +<NULL>. When a tape has a permanent name, the Backup +System uses it instead of the AFS tape name in most prompts and when referring +to the tape in output from backup commands. The permanent +name persists until you again include the -pname argument to the +backup labeltape command, regardless of the tape's contents +and of how often you recycle the tape or use the backup labeltape +command without the -pname argument. +

To write an AFS tape name on the label, provide a value for the +-name argument that matches the volume set name and the final +element in the dump level pathname of the initial dump that you plan to write +to the tape, and an index that indicates the tape's place in the sequence +of tapes for the dump set. The format is as follows: +

   volume_set_name.dump_level_name.tape_index
+

If you omit the -name argument, the Backup System sets the AFS +tape name to <NULL>. The Backup System automatically +constructs and records the appropriate name when you later write an initial +dump to the tape by using the backup dump or backup +savedb command. +

You cannot use the -name argument if the tape already has a +permanent name. To erase a tape's permanent name, provide a null +value to the -pname argument by issuing the following +command: +

   % backup labeltape -pname ""
+

Recording a Capacity on the Label

To record the tape's capacity on the label, specify a number of +kilobytes as the -size argument. If you omit this argument +the first time you label a tape, the Backup System records the default tape +capacity associated with the specified port offset in the +/usr/afs/backup/tapeconfig file on the Tape Coordinator +machine. If the tape's capacity is different (in particular, +larger) than the capacity recorded in the tapeconfig file, it is +best to record a capacity on the label before using the tape. Once set, +the value in the label's capacity field persists until you again use the +-size argument to the backup labeltape command. +For a discussion of the appropriate capacity to record for tapes, see Configuring the tapeconfig File. +

To read a tape's label, use the backup readlabel +command. +

Most tapes also come with an adhesive label you can apply to the exterior +casing. To help you easily identify a tape, record at least the +tape's permanent and AFS tape names on the adhesive label. +Depending on the recycling scheme you use, it can be useful to record other +information, such as the dump ID, dump creation date, and expiration date of +each dump you write to the tape. + + +

To label a tape

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If the Tape Coordinator for the tape device that is to perform the +operation is not already running, open a connection to the appropriate Tape +Coordinator machine and issue the butc command, for which complete +instructions appear in To start a Tape Coordinator process. +
```
   % butc [<port offset>] [-noautoquery]
+
```
+
Place the tape in the device. +
Optional. Issue the backup command to enter +interactive mode, if you want to label multiple tapes or issue additional +commands after labeling the tape. The interactive prompt appears in the +following step. +
```
   % backup
+
```
+
Issue the (backup) labeltape command to label the tape. +
```
   backup> labeltape [-name <tape name, defaults to NULL>]  \
+      [-size <tape size in Kbytes, defaults to size in tapeconfig>]  \
+      [-portoffset <TC port offset>] [-pname <permanent tape name>]
+
```
+
where +
+
la +
Is the shortest acceptable abbreviation of labeltape. +
-name +
Specifies the AFS tape name to record on the label. Include this +argument or the -pname argument, but not both. If you omit +this argument, the AFS tape name is set to <NULL>. If you +provide it, it must have the following format. +
```
volume_set_name.dump_level_name.tape_index
+
```
+
+
for the tape to be acceptable for use in a future backup dump +operation. The volume_set_name must match the volume set name +of the initial dump to be written to the tape, dump_level_name must +match the last element of the dump level pathname at which the volume set is +to be dumped, and tape_index must correctly indicate the tape's +place in the sequence of tapes that house the dump set; indexing begins +with the number 1 (one). +
-size +
Specifies the tape capacity to record on the label. If you are +labeling the tape for the first time, you need to include this argument only +if the tape's capacity differs from the capacity associated with the +specified port offset in the /usr/afs/backup/tapeconfig file on the +Tape Coordinator machine. +
If you provide a value, it is an integer value followed by a letter that +indicates units, with no intervening space. A unit value of +k or K indicates kilobytes, m or M +indicates megabytes, and g or G indicates +gigabytes. If you omit the units letter, the default is +kilobytes. +
-portoffset +
Specifies the port offset number of the Tape Coordinator handling the tape +or backup data file for this operation. You must provide this argument +unless the default value of 0 (zero) is appropriate. +
-pname +
Specifies the permanent name to record on the label. It can be up +to 32 characters in length, and include any alphanumeric characters. +Avoid metacharacters that have a special meaning to the shell, to avoid having +to mark them as literal in commands issued at the shell prompt. +
Include this argument or the -name argument, but not +both. When you provide this argument, the AFS tape name is set to +<NULL>. If you omit this argument, any existing permanent +name is retained. +
+
If you did not include the -noautoquery flag when you issued +the butc command, or if the device's device configuration file +includes the instruction AUTOQUERY YES, then the Tape Coordinator +prompts you to place the tape in the device's drive. You have +already done so, but you must now press <Return> to indicate +that the tape is ready for labeling. +

+ + +

To read the label on a tape

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If the Tape Coordinator for the tape device that is to perform the +operation is not already running, open a connection to the appropriate Tape +Coordinator machine and issue the butc command, for which complete +instructions appear in To start a Tape Coordinator process. +
```
   % butc [<port offset>] [-noautoquery]
+
```
+
Place the tape in the device. +
Optional. Issue the backup command to enter +interactive mode, if you want to label multiple tapes or issue additional +commands after labeling the tape. The interactive prompt appears in the +following step. +
```
   % backup
+
```
+
Issue the (backup) readlabel command to read the label on the +tape. +
```
   backup> readlabel [<TC port offset>]
+
```
+
where +
+
rea +
Is the shortest acceptable abbreviation of readlabel. +
TC port offset +
Specifies the port offset number of Tape Coordinator handling the tape or +backup data file for this operation. You must provide this argument +unless the default value of 0 (zero) is appropriate. +
+
If you did not include the -noautoquery flag when you issued +the butc command, or the device's device configuration file +includes the instruction AUTOQUERY YES instruction, then the Tape +Coordinator prompts you to place the tape in the device's drive. +You have already done so, but you must now press <Return> to +indicate that the tape is ready for reading. +

Information from the tape label appears both in the backup +command window and in the Tape Coordinator window. The output in the +command window has the following format: +

   Tape read was labelled: tape_name (initial_dump_ID)
+        size: size KBytes
+

where tape_name is the tape's permanent name (if it has one) +or AFS tape name, initial_dump_ID is the dump ID of the initial dump +on the tape, and size is the capacity recorded on the label, in +kilobytes. +

The information in the Tape Coordinator window is more extensive. +The tape's permanent name appears in the tape name field and +its AFS tape name in the AFS tape name field. If either name +is undefined, a value of <NULL> appears in the field +instead. The capacity recorded on the label appears in the +size field. Other fields in the output report the creation +time, dump level name, and dump ID of the initial dump on the tape +(creationTime, dump path, and dump id +respectively). The cell field reports the cell in which the +dump operation was performed, and the useCount field reports the +number of times the tape has been relabeled, either with the backup +labeltape command or during a dump operation. For further +details, see the command's reference page in the IBM AFS +Administration Reference. +

If the tape has no label, or if the drive is empty, the following message +appears at the command shell: +

   Failed to read tape label.
+

The following example illustrates the output in the command shell for a +tape in the device with port offset 1: +

   % backup readlabel 1
+   Tape read was labelled: monthly_guest (917860000)
+        size: 2150000 KBytes
+

The following output appears in the Tape Coordinator window at the same +time: +

   Tape label
+   ----------
+   tape name = monthly_guest
+   AFS tape name = guests.monthly.3
+   creationTime =  Mon Feb  1 04:06:40 1999
+   cell = abc.com
+   size = 2150000 Kbytes
+   dump path = /monthly
+   dump id = 917860000
+   useCount = 44
+   -- End of tape label --
+

Automating and Increasing the Efficiency of the Backup Process

+ + +

The Backup System includes several optional features to help you automate +the backup process in your cell and make it more efficient. By +combining several of the features, you can dump volume data to tape with +minimal human intervention in most cases. To take advantage of many of +the features, you create a device configuration file in the +/usr/afs/backup directory for each tape device that participates in +automated operations. For general instructions on creating the device +configuration file, see Creating a Device Configuration File. The following list refers you to sections that +describe each feature in greater detail. +

You can use tape stackers and jukeboxes to perform backup +operations. These are tape drives with an attached unit that stores +several tapes and can physically insert and remove them from the tape reader +(tape drive) without human intervention, meaning that no operator has to be +present even for backup operations that require several tapes. To use a +stacker or jukebox with the Backup System, include the MOUNT and +UNMOUNT instructions in its device configuration file. See Invoking a Device's Tape Mounting and Unmounting Routines. +
You can suppress the Tape Coordinator's default prompt for the +initial tape that it needs for a backup operation, again eliminating the need +for a human operator to be present when a backup operation begins. (You +must still insert the correct tape in the drive at some point before the +operation begins.) To suppress the initial prompt, include the +-noautoquery flag on the butc command, or assign the +value NO to the AUTOQUERY instruction in the device +configuration file. See Eliminating the Search or Prompt for the Initial Tape. +
You can suppress the prompts that the Tape Coordinator otherwise generates +when it encounters several types of errors. When you use this feature, +the Tape Coordinator instead responds to the errors in a default manner, which +generally allows the operation to continue without human intervention. +To suppress prompts about error conditions, assign the value NO to +the ASK instruction in the device configuration file. See Enabling Default Responses to Error Conditions. +
You can suppress the Backup System's default verification that the +AFS tape name on a tape that has no permanent name matches the name derived +from the volume set and dump level names of the initial dump the Backup System +is writing to the tape. This enables you to recycle a tape without +first relabeling it, as long as all dumps on it are expired. To +suppress name checking, assign the value NO to the +NAME_CHECK instruction in the device configuration file. See +Eliminating the AFS Tape Name Check. +
You can promote tape streaming (the most efficient way for a tape device +to operate) by setting the size of the memory buffer the Tape Coordinator uses +when transferring volume data between the file system and the device. +To set the buffer size, include the BUFFERSIZE instruction in the +device configuration file. See Setting the Memory Buffer Size to Promote Tape Streaming. +
You can write dumps to a backup data file on the local disk of +the Tape Coordinator machine, rather than to tape. You can then +transfer the backup data file to a data-archiving system, such as a +hierarchical storage management (HSM) system, that you use in conjunction with +AFS and the Backup System. Writing a dump to a file is usually more +efficient that issuing the equivalent vos dump commands +individually. To write dumps to a file, include the FILE +instruction in the device configuration file. See Dumping Data to a Backup Data File. +

There are two additional ways to increase backup automation and efficiency +that do not involve the device configuration file: +

You can schedule one or more backup dump commands to run at +specified times. This enables you to create backups at times of low +system usage, without requiring a human operator to be present. You can +schedule a single dump operation for a future time, or multiple operations to +run at various future times. See Scheduling Dumps. +
You can append dumps to a tape that already has other dumps on it. +This enables you to use as much of a tape's capacity as possible. +The appended dumps do not have be related in any way to one another or to the +initial dump on the tape, but grouping dumps appropriately can reduce the +number of necessary tape changes during a restore operation. To append +a dump, include the -append argument to the backup dump +command. See Appending Dumps to an Existing Dump Set. +

Creating a Device Configuration File

+ + + + +

To use many of the features that automate backup operations, create a +configuration file for each tape device in the /usr/afs/backup +directory on the local disk of the Tape Coordinator machine that drives the +device. The filename has the following form: +

CFG_device_name +

where device_name represents the name of the tape device or backup +data file (see Dumping Data to a Backup Data File to learn about writing dumps to a file rather than to +tape). +

For a tape device, construct the device_name portion of the name +by stripping off the initial /dev/ string with which all UNIX +device names conventionally begin, and replacing 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, construct the device_name portion by +stripping off the initial slash (/) and replacing 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. +

Creating a device configuration file is optional. If you do not want +to take advantage of any of the features that the file provides, you do not +have to create it. +

You can include one of each of the following instructions in any order in a +device configuration file. All are optional. Place each +instruction on its own line, but do not include any newline +(<Return>) characters within an instruction. +

MOUNT and UNMOUNT +: Identify a script of routines for mounting and unmounting tapes in a tape +stacker or jukebox's drive as needed. See Invoking a Device's Tape Mounting and Unmounting Routines. +
AUTOQUERY +: Controls whether the Tape Coordinator prompts for the first tape it needs +for a backup operation. See Eliminating the Search or Prompt for the Initial Tape. +
ASK +: Controls whether the Tape Coordinator asks you how to respond to certain +error conditions. See Enabling Default Responses to Error Conditions. +
NAME_CHECK +: Controls whether the Tape Coordinator verifies that an AFS tape name +matches the initial dump you are writing to the tape. See Eliminating the AFS Tape Name Check. +
BUFFERSIZE +: Sets the size of the memory buffer the Tape Coordinator uses when +transferring data between a tape device and a volume. See Setting the Memory Buffer Size to Promote Tape Streaming. +
FILE +: Controls whether the Tape Coordinator writes dumps to, and restores data +from, a tape device or a backup data file. See Dumping Data to a Backup Data File. +

+ + + + + + +

Invoking a Device's Tape Mounting and Unmounting Routines

A tape stacker or jukebox helps you automate backup +operations because it can switch between multiple tapes during an operation +without human intervention. To take advantage of this feature, include +the MOUNT and optionally UNMOUNT instructions in the +device configuration file that you write for the stacker or jukebox. +The instructions share the same syntax: +

   MOUNT filename
+   UNMOUNT filename
+

where filename is the pathname on the local disk of a script or +program you have written that invokes the routines defined by the +device's manufacturer for mounting or unmounting a tape in the +device's tape drive. (For convenience, the following discussion +uses the term script to refers to both scripts and +programs.) The script usually also contains additional logic that +handles error conditions or modifies the script's behavior depending on +which backup operation is being performed. +

You can refer to different scripts with the MOUNT or +UNMOUNT instructions, or to a single script that invokes both +mounting and unmounting routines. The scripts inherit the local +identity and AFS tokens associated with to the issuer of the butc +command. +

You need to include a MOUNT instruction in the device +configuration file for all tape devices, but the need for an +UNMOUNT instruction depends on the tape-handling routines that the +device's manufacturer provides. Some devices, usually stackers, +have only a single routine for mounting tapes, which also automatically +unmounts a tape whose presence prevents insertion of the required new +tape. In this case, an UNMOUNT instruction is not +necessary. For devices that have separate mounting and unmounting +routines, you must include an UNMOUNT instruction to remove a tape +when the Tape Coordinator is finished with it; otherwise, subsequent +attempts to run the MOUNT instruction fail with an error. +

When the device configuration file includes a MOUNT instruction, +you must stock the stacker or jukebox with the necessary tapes before running +a backup operation. Many jukeboxes are able to search for the required +tape by reading external labels (such as barcodes) on the tapes, but many +stackers can only switch between tapes in sequence and sometimes only in one +direction. In the latter case, you must also stock the tapes in the +correct order. +

To obtain a list of the tapes required for a restore operation so that you +can prestock them in the tape device, include the -n flag on the +appropriate backup command (backup diskrestore, +backup volrestore, or backup volsetrestore). For +a dump operation, it is generally sufficient to stock the device with more +tapes than the operation is likely to require. You can prelabel the +tapes with permanent names or AFS tape names, or not prelabel them at +all. If you prelabel the tapes for a dump operation with AFS tape +names, then it is simplest to load them into the stacker in sequential order +by tape index. But it is probably simpler still to prelabel tapes with +permanent tape names or use unlabeled tapes, in which case the Backup System +generates and applies the appropriately indexed AFS tape name itself during +the dump operation. +

How the Tape Coordinator Uses the MOUNT and UNMOUNT Instructions

When you issue the butc command to initialize the Tape +Coordinator for a given tape device, the Tape Coordinator looks for the device +configuration file called /usr/afs/backup/CFG_device_name +on its local disk, where device_name has the format described in Creating a Device Configuration File. If the file exists and contains a MOUNT +instruction, then whenever the Tape Coordinator needs a tape, it executes the +script named by the instruction's filename argument. +

If the device configuration file does not exist, or does not include a +MOUNT instruction, then whenever the Tape Coordinator needs a tape, +it generates a prompt in its window instructing the operator to insert the +necessary tape. The operator must insert the tape and press +<Return> before the Tape Coordinator continues the backup +operation. +

Note, however, that you can modify the Tape Coordinator's behavior +with respect to the first tape needed for an operation, by setting the +AUTOQUERY instruction in the device configuration file to +NO, or including the -noautoquery flag to the +butc command. In this case, the Tape Coordinator does not +execute the MOUNT instruction or prompt for a tape at the start of +an operation, because it expects to find the required first tape in the +drive. See Eliminating the Search or Prompt for the Initial Tape. +

If there is an UNMOUNT instruction in the device configuration +file, then whenever the Tape Coordinator closes the tape device, it executes +the script named by the instruction's filename argument. +It executes the script only once, and regardless of whether the +close operation on the device succeeded or not. If the +device configuration file does not include an UNMOUNT instruction, +then the Tape Coordinator takes no action. +

The Available Parameters and Required Exit Codes

When the Tape Coordinator executes the MOUNT script, it +passes in five parameters, ordered as follows. You can use the +parameters in your script to refine its response to varying circumstances that +can arise during a backup operation. +

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. +

Your MOUNT script must return one of the following exit codes to +tell the Tape Coordinator whether or not it mounted the tape +successfully: +

Code 0 (zero) indicates a successful mount, and the Tape +Coordinator continues the backup operation. If the script or program +called by the MOUNT instruction does not return this exit code, the +Tape Coordinator never calls the UNMOUNT instruction. +
Code 1 indicates that mount attempt failed. The Tape +Coordinator terminates the backup operation. +
Any other code indicates that the script was unable to access the correct +tape. The Tape Coordinator prompts the operator to insert it. +

When the Tape Coordinator executes the UNMOUNT script, it passes +in two parameters in the following order. +

The tape device's pathname (as specified in the +/usr/afs/backup/tapeconfig file) +
The tape operation, which is always unmount. +

The following example script uses two of the parameters passed to it by the +Backup System: tries and operation. It +follows the recommended practice of exiting 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 +(is a restore operation, for example). +

   #! /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}
+

+ + + + +

Eliminating the Search or Prompt for the Initial Tape

By default, the Tape Coordinator obtains the first tape it +needs for a backup operation by reading the device configuration file for the +appropriate tape device. If there is a MOUNT instruction in +the file, the Tape Coordinator executes the referenced script. If the +device configuration file does not exist or does not have a MOUNT +instruction in it, the Tape Coordinator prompts you to insert the correct tape +and press <Return>. +

If you know in advance that an operation requires a tape, you can increase +efficiency by placing the required tape in the drive before issuing the +backup command and telling the Tape Coordinator's to skip its +initial tape-acquisition steps. This both enables the operation to +begin more quickly and eliminates that need for you to be present to insert a +tape. +

There are two ways to bypass the Tape Coordinator's initial +tape-acquisition steps: +

Include the instruction AUTOQUERY NO in the device +configuration file +
Include the -noautoquery flag to the butc command +

To avoid any error conditions that require operator attention, be sure that +the tape you are placing in the drive does not contain any unexpired dumps and +is not write protected. If there is no permanent name on the +tape's label and you are creating an initial dump, make sure that the AFS +tape name either matches the volume set and dump set names or is +<NULL>. Alternatively, suppress the Tape +Coordinator's name verification step by assigning the value NO +to the NAME_CHECK instruction in the device configuration file, as +described in Eliminating the AFS Tape Name Check. + + + +

Enabling Default Responses to Error Conditions

By default, the Tape Coordinator asks you how to respond +when it encounters certain error conditions. To suppress the prompts +and cause the Tape Coordinator to handle the errors in a predetermined manner, +include the instruction ASK NO in the device configuration +file. If you assign the value YES, or omit the +ASK instruction completely, the Tape Coordinator prompts you for +direction when it encounters one of the errors. +

The following list describes the error conditions and the Tape +Coordinator's response to them. +

The Backup System is unable to dump a volume while running the backup +dump command. When you assign the value NO, the Tape +Coordinator omits the volume from the dump and continues the operation. +When you assign the value YES, it prompts to ask if you want to try +to dump the volume again immediately, to omit the volume from the dump but +continue the operation, or to terminate the operation. +
The Backup System is unable to restore a volume while running the +backup diskrestore, backup volrestore, or backup +volsetrestore command. When you assign the value NO, +the Tape Coordinator continues the operation, omitting the problematic volume +but restoring the remaining ones. When you assign the value +YES, it prompts to ask if you want to omit the volume and continue +the operation, or to terminate the operation. +
The Backup System cannot determine if the dump set includes any more tapes +while running the backup scantape command (the command's +reference page in the IBM AFS Administration Reference discusses +possible reasons for this problem). When you assign the value +NO, the Tape Coordinator proceeds as though there are more tapes +and invokes the MOUNT script named in the device configuration +file, or prompts the operator to insert the next tape. When you assign +the value YES, it prompts to ask if there are more tapes to +scan. +
The Backup System determines that the tape contains an unexpired dump +while running the backup labeltape command. When you assign +the value NO, it terminates the operation without relabeling the +tape. With a YES value, the Tape Coordinator prompts to ask +if you want to relabel the tape anyway. +

+ + + + +

Eliminating the AFS Tape Name Check

If a tape does not have a permanent name and you are writing +an initial dump to it, then by default the Backup System verifies that the +tape's AFS tape name is acceptable. It accepts three types of +values: +

A name that reflects the volume set and dump level of the initial dump and +the tape's place in the sequence of tapes for the dump set, as described +in Dump Names and Tape Names. If the tape does not already have a permanent name, +you can assign the AFS tape name by using the -name argument to the +backup labeltape command. +
A <NULL> value, which results when you assign a permanent +name, or provide no value for the backup labeltape command's +-name argument. +
No AFS tape name at all, indicating that you have never labeled the tape +or written a dump to it. +

To bypass the name check, include the NAME_CHECK NO instruction +in the device configuration file. This enables you to recycle a tape +without first relabeling it, as long as all dumps on it are expired. +(If a tape has unexpired dumps on it but you want to recycle it anyway, you +must use the backup labeltape command to relabel it first. +For this to work, the ASK NO instruction cannot appear in the +device configuration file.) +

Setting the Memory Buffer Size to Promote Tape Streaming

By default, the Tape Coordinator uses a 16-KB memory 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. Similarly, during a +restore operation the Tape Coordinator by default buffers 32 KB of data from +the tape device 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. +

To determine if altering the buffer size is helpful for your configuration, +observe the tape device in operation to see if it is streaming, or consult the +manufacturer. To set the buffer size, include the BUFFERSIZE +instruction in the device configuration file. It 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 size +value and the units letter. +

Dumping Data to a Backup Data File

You can write dumps to a backup data file rather +than to tape. This is useful if, for example, you want to transfer the +data to a data-archiving system, such as a hierarchical storage management +(HSM) system, that you use in conjunction with AFS and the Backup +System. You can restore data from a backup data file into the file +system as well. Using a backup data file is usually more efficient than +issuing the equivalent vos dump and vos restore commands +individually for multiple volumes. +

Writing to a backup data file is simplest if it is on the local disk of the +Tape Coordinator machine, but you can also write the file to an NFS-mounted +partition that resides on a remote machine. It is even acceptable to +write to a file in AFS, provided that the access control list (ACL) on its +parent directory grants the necessary permissions, but it is somewhat circular +to back up AFS data into AFS itself. +

If the backup data file does not already exist when the Tape Coordinator +attempts to write a dump to it, the Tape Coordinator creates it. For a +restore operation to succeed, the file must exist and contain volume data +previously written to it during a backup dump 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. +

Before writing to a backup data file, you need to configure the file as +though it were a tape device. +
Note: A file pathname, rather than a tape device name, must appear in the third +field of the /usr/afs/backup/tapeconfig file when the FILE +YES instruction appears in the device configuration file, and vice +versa. If the tapeconfig file instead refers to a tape +device, dump operations appear to succeed but are inoperative. You +cannot restore data that you 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. +
+

To configure a backup data file

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Optional. Issue the backup command to enter +interactive mode. +
```
   # backup
+
```
+
Choose the port offset number to assign to the file. If necessary, +display previously assigned port offsets by issuing the (backup) +listhosts command, which is fully described in To display the list of configured Tape Coordinators. +
```
   backup> listhosts
+
```
+
As for a tape device, acceptable values are the integers 0 +(zero) through 58510 (the Backup System can track a maximum of +58,511 port offset numbers). Each port offset must be unique in the +cell, but you can associate any number them with a single Tape Coordinator +machine. You do not have to assign port offset numbers +sequentially. +
Issue the (backup) addhost command to register the backup data +file's port offset in the Backup Database. +
```
   backup> addhost <tape machine name> [<TC port offset>]
+
```
+
where +
+
addh +
Is the shortest acceptable abbreviation of addhost. +
tape machine name +
Specifies the fully qualified hostname of the Tape Coordinator machine you +invoke to write to the backup data file. +
TC port offset +
Specifies the file's port offset number. You must provide this +argument unless the default value of 0 (zero) is +appropriate. +
+
Using a text editor, create an entry for the backup +data file in the local /usr/afs/backup/tapeconfig file, using the +standard syntax: +
```
   [capacity  filemark_size]  device_name   port_offset
+
```
+
where +
+
capacity +
Specifies the amount of space on the partition that houses the backup data +file that you want to make available for the file. To avoid the +complications that arise from filling up the partition, it is best to provide +a value somewhat smaller than the actual amount of space you expect to be +available when the dump operation runs, and never larger than the maximum file +size allowed by the operating system. +
Specify a numerical value followed by a letter that indicates units, with +no intervening space. The letter k or K indicates +kilobytes, m or M indicates megabytes, and g +or G indicates gigabytes. If you omit the units letter, the +default is kilobytes. If you leave this field empty, the Tape +Coordinator uses the maximum acceptable value (2048 GB or 2 TB). Also +leave the filemark_size field empty in that case. +
filemark_size +
Specify the value 0 (zero) or leave both this field and the +capacity field empty. In the latter case, the Tape Coordinator +also uses the value zero. +
device_name +
Specifies the complete pathname of the backup data file. Rather +than specifying an actual file pathname, 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 provides these advantages: +
- It makes the device_name portion of the +CFG_device_name, of the +TE_device_name, and of the +TL_device_name filenames as short as possible. +Because the symbolic link is in the /dev directory as though it is +a tape device, you strip off the entire /dev/ prefix when forming +the filename, instead of just the initial slash (/). If, for +example, the symbolic link is called /dev/FILE, the device +configuration file's name is CFG_FILE, whereas if the actual +pathname /var/tmp/FILE appears in the tapeconfig file, +the configuration 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 +(for example, because the partition housing the backup data file becomes +full). The Tape Coordinator's reaction to this problem is to +invoke the MOUNT script, or to prompt you if the MOUNT +instruction does not appear in the configuration file. +
  - If there is a MOUNT script, you can prepare for this situation +by adding a subroutine to the script 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 you +manually to change the symbolic link to point to another backup data file and +then press <Return> to signal that the Tape Coordinator can +continue the operation. +
  +
  If this field names the actual file, there is no way to recover from +exhausting the space on the partition. You cannot change the +tapeconfig file in the middle of an operation. +
+
port_offset +
Specifies the port offset number that you chose for the backup data +file. +
+
Create the device configuration file CFG_device_name +in the Tape Coordinator machine's /usr/afs/backup +directory. Include the FILE YES instruction in the +file. +
Construct the device_name portion of the name based on the device +name you recorded in the tapeconfig file in Step 6. If, as recommended, you recorded a symbolic link +name, strip off the /dev/ string and replace any other slashes +(/) in the name with underscores (_). For +example, CFG_FILE is the appropriate name if the symbolic link is +/dev/FILE. If you recorded the name of an actual file, then +strip off the initial slash only and replace any other slashes in the name +with underscores. For a backup data file called +/var/tmp/FILE, the appropriate device configuration filename is +CFG_var_tmp_FILE. +
If you chose in Step 6 to record a symbolic link name in the device_name +field of the tapeconfig entry, then you must do one of the +following: +
- Use the ln -s command to create the appropriate symbolic link +in the /dev directory +
- Write a script that initializes the backup data file in this way, and +include a MOUNT instruction in the device configuration file to +invoke the script. An example script appears following these +instructions. +
+

You do not need to create the backup data file itself, because the Tape +Coordinator does so if the file does not exist when the dump operation +begins. +

The following example script illustrates how you can automatically create a +symbolic link to the backup data file during the preparation phase for writing +to the file. 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 values of the tapename and +tapeid parameters passed to it by the Backup System when +constructing the filename. +

The routine makes use of two other parameters as well: +tries and operation. 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. +

   #! /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}
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd012.htm b/doc/html/AdminGuide/auagd012.htm new file mode 100644 index 0000000..11835e8 --- /dev/null +++ b/doc/html/AdminGuide/auagd012.htm @@ -0,0 +1,2765 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Backing Up and Restoring AFS Data

The instructions in this chapter explain how to back up and +restore AFS data and to administer the Backup Database. They assume +that you have already configured all of the Backup System components by +following the instructions in Configuring the AFS Backup System. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + + + + + + + + + + +
Enter interactive mode + backup (interactive) +
Leave interactive mode + (backup) quit +
List operations in interactive mode + (backup) jobs +
Cancel operation in interactive mode + (backup) kill +
Start Tape Coordinator + butc +
Stop Tape Coordinator + <Ctrl-c> +
Check status of Tape Coordinator + backup status +
Back up data + backup dump +
Display dump records + backup dumpinfo +
Display volume's dump history + backup volinfo +
Scan contents of tape + backup scantape +
Restore volume + backup volrestore +
Restore partition + backup diskrestore +
Restore group of volumes + backup volsetrestore +
Verify integrity of Backup Database + backup dbverify +
Repair corruption in Backup Database + backup savedb and backup restoredb +
Delete dump set from Backup Database + backup deletedump +
+

Using the Backup System's Interfaces

+ +

When performing backup operations, you interact with three Backup System +components: +

You initiate backup operations by issuing commands from the +backup suite. You can issue the commands in a command shell +(or invoke them in a shell script) on any AFS client or server machine from +which you can access the backup binary. In the conventional +configuration, the binary resides in the /usr/afs/bin directory on +a server machine and the /usr/afsws/etc directory on a client +machine. +
The suite provides an interactive mode, in which you can issue multiple +commands over a persistent connection to the Backup Server and the Volume +Location (VL) Server. Interactive mode has several convenient +features. For a discussion and instructions, see Using Interactive and Regular Command Mode. +
Note that some operating systems include a backup command of +their own. You must configure machines that run such an operating +system to ensure that you are accessing the desired backup +binary. +
Before you perform a backup operation that involves reading or writing to +a tape device or backup data file, you must open a dedicated connection to the +appropriate Tape Coordinator machine and start the Tape Coordinator +(butc) process that handles the device or file. The +butc process must continue to run over the dedicated connection as +long as it is executing an operation or is to be available to execute +one. For further discussion and instructions, see Starting and Stopping the Tape Coordinator Process. +
The Backup Server (buserver) process must be running on +database server machines, because most backup operations require accessing or +changing information in the Backup Database. The IBM AFS Quick +Beginnings explains how to configure the Backup Server. +

For consistent Backup System performance, the AFS build level of all three +binaries (backup, butc, and buserver) must +match. For instructions on displaying the build level, see Displaying A Binary File's Build Level. +

Performing Backup Operations as the Local Superuser Root or in a Foreign Cell

+ + + +

By default, the volumes and Backup Database involved in a backup operation +must reside on server machines that belong to the cell named in the +/usr/vice/etc/ThisCell files on both the Tape Coordinator machine +and the machine where you issue the backup command. Also, to +issue most backup commands you must have AFS tokens for an identity +listed in the local cell's /usr/afs/etc/UserList file (which +by convention is the same on every server machine in a cell). You can, +however, perform backup operations on volumes or the Backup Database from a +foreign cell, or perform backup operations while logged in as the local +superuser root rather than as a privileged AFS identity. +

To perform backup operations on volumes that reside in a foreign cell using +machines from the local cell, you must designate the foreign cell as the cell +of execution for both the Tape Coordinator and the backup command +interpreter. Use one of the two following methods. For either +method, you must also have tokens as an administrator listed in the foreign +cell's /usr/afs/etc/UserList file. +

Before issuing backup commands and the butc command, +set the AFSCELL environment variable to the foreign cell name in both command +shells. +
Include the -cell argument to the butc and all +backup commands. If you include the argument on the +backup (interactive) command, it applies to all commands issued +during the interactive session. +

To perform backup operations without having administrative AFS tokens, you +must log on as the local superuser root on both the Tape +Coordinator machine and the machine where you issue backup +commands. Both machines must be server machines, or at least have a +/usr/afs/etc/KeyFile file that matches the file on other server +machines. Then include the -localauth argument on both the +butc command and all backup commands (or the backup +(interactive) command). The Tape Coordinator and +backup command interpreter construct a server ticket using the +server encryption key with the highest key version number in the local +/usr/afs/etc/KeyFile file, and present it to the Backup Server, +Volume Server, and VL Server that belong to the cell named in the local +/usr/afs/etc/ThisCell file. The ticket never expires. +

You cannot combine the -cell and -localauth options +on the same command. Also, each one overrides the local cell setting +defined by the AFSCELL environment variable or the +/usr/vice/etc/ThisCell file. +

Using Interactive and Regular Command Mode

+ + +

The backup command suite provides an interactive +mode, in which you can issue multiple commands over a persistent +connection to the Backup Server and the VL Server. Interactive mode +provides the following features: +

The backup> prompt replaces the usual command shell +prompt. +
You omit the initial backup string from command names. +Type only the operation code and option names. +
You cannot issue commands that do not belong to the backup +suite. +
If you assume an administrative AFS identity or specify a foreign cell as +you enter interactive mode, it applies to all commands issued during the +interactive session. See Performing Backup Operations as the Local Superuser Root or in a Foreign Cell. +
You do not need to enclose shell metacharacters in double quotes. +

+ + +

When you initiate a backup operation in interactive mode, the Backup System +assigns it a job ID number. You can display the list of +current and pending operations with the (backup) jobs command, for +which instructions appear in To display pending or running jobs in interactive mode. (In both regular and interactive modes, the Tape +Coordinator also assigns a task ID number to each operation you +initiate with a backup command. You can track task ID +numbers with the backup status command. See Starting and Stopping the Tape Coordinator Process.) +

You can cancel an operation in interactive mode with the (backup) +kill command, for which instructions appear in To cancel operations in interactive mode. However, it is best not to interrupt a dump +operation because the resulting dump is incomplete, and interrupting a restore +operation can leave volumes in an inconsistent state, or even completely +remove them from the server machine. For further discussion, see Backing Up Data and Restoring and Recovering Data. +

The (backup) jobs and (backup) kill commands are +available only in interactive mode and there is no equivalent functionality in +regular command mode. + + + + +

To enter interactive mode

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. Entering interactive mode does +not itself require privilege, but most other backup commands do, +and the AFS identity you assume when entering the mode applies to all commands +you issue within it. If necessary, issue the bos listusers +command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the backup (interactive) command at the system +prompt. The backup> prompt appears. You can include +either, but not both, of the -localauth and -cell +options, as discussed in Performing Backup Operations as the Local Superuser Root or in a Foreign Cell. +
```
   % backup
+   backup>
+
```
+

+ + + + +

To exit interactive mode

Issue the quit command at the backup> prompt. +The command shell prompt reappears when the command succeeds, which it does +only if there are no jobs pending or currently running. To display and +cancel pending or running jobs, follow the instructions in To display pending or running jobs in interactive mode and To cancel operations in interactive mode. +
```
   backup> quit
+   %
+
```
+

+ + + + + + +

To display pending or running jobs in interactive mode

Issue the jobs command at the backup> prompt. +
+
```
   backup> jobs
+
```
+
where +
+
j +
Is the shortest acceptable abbreviation of jobs. +
+

The output always includes the expiration date and time of the tokens that +the backup command interpreter is using during the current +interactive session, in the following format: +

   date   time: TOKEN EXPIRATION
+

If the execution date and time specified for a scheduled dump operation is +later than date time, then its individual line (as described in the +following paragraphs) appears below this line to indicate that the current +tokens will not be available to it. +

If the issuer of the backup command included the +-localauth flag when entering interactive mode, the line instead +reads as follows: +

   :  TOKEN NEVER EXPIRES
+

The entry for a scheduled dump operation has the following format: +

   Job job_ID:  timestamp:  dump  volume_set  dump_level
+

where +

job_ID +: Is a job identification number assigned by the Backup System. +
timestamp +: Indicates the date and time the dump operation is to begin, in the format +month/date/year +hours:minutes (in 24-hour format) +
volume_set +: Indicates the volume set to dump. +
dump_level +: Indicates the dump level at which to perform the dump operation. +

The line for a pending or running operation of any other type has the +following format: +

   Job job_ID:  operation  status
+

where +

job_ID +

Is a job identification number assigned by the Backup System. +

operation +

Identifies the operation the Tape Coordinator is performing, which is +initiated by the indicated command: +

Dump (dump name) +

Initiated by the backup dump command. The dump +name has the following format: +

volume_set_name.dump_level_name +

Restore +

Initiated by the backup diskrestore, backup +volrestore, or backup volsetrestore command. +

Labeltape (tape_label) +

Initiated by the backup labeltape command. The +tape_label is the name specified by the backup labeltape +command's -name or -pname argument. +

Scantape +

Initiated by the backup scantape command. +

SaveDb +

Initiated by the backup savedb command. +

RestoreDb +

Initiated by the backup restoredb command. +

status +

Indicates the job's current status in one of the following +messages. If no message appears, the job is either still pending or has +finished. +

number Kbytes, volume volume_name +: For a running dump operation, indicates the number of kilobytes copied to +tape or a backup data file so far, and the volume currently being +dumped. +
number Kbytes, restore.volume +: For a running restore operation, indicates the number of kilobytes copied +into AFS from a tape or a backup data file so far. +
[abort requested] +: The (backup) kill command was issued, but the termination +signal has yet to reach the Tape Coordinator. +
[abort sent] +: The operation is canceled by the (backup) kill command. +Once the Backup System removes an operation from the queue or stops it from +running, it no longer appears at all in the output from the command. +
[butc contact lost] +: The backup command interpreter cannot reach the Tape +Coordinator. The message can mean either that the Tape Coordinator +handling the operation was terminated or failed while the operation was +running, or that the connection to the Tape Coordinator timed out. +
[done] +: The Tape Coordinator has finished the operation. +
[drive wait] +: The operation is waiting for the specified tape drive to become +free. +
[operator wait] +: The Tape Coordinator is waiting for the backup operator to insert a tape +in the drive. +

+ + + + + +

To cancel operations in interactive mode

Issue the jobs command at the backup> prompt, to +learn the job ID number of the operation you want to cancel. For +details, see To display pending or running jobs in interactive mode. +
```
   backup> jobs
+
```
+
Issue the (backup) kill command to cancel the operation. +
+
```
   backup> kill <job ID or dump set name>
+
```
+
where +
+
k +
Is the shortest acceptable abbreviation of kill. +
job ID or dump set name +
Specifies either the job ID number of the operation to cancel, as reported +by the jobs command, or for a dump operation only, the dump name in +the format volume_set_name.dump_level_name. +
+

Starting and Stopping the Tape Coordinator Process

+ +

Before performing a backup operation that reads from or writes to a tape +device or backup data file, you must start the Tape Coordinator +(butc) process that handles the drive or file. This section +explains how to start, stop, and check the status of a Tape Coordinator +process. To use these instructions, you must have already configured +the Tape Coordinator machine and created a Tape Coordinator entry in the +Backup Database, as instructed in Configuring Tape Coordinator Machines and Tape Devices. +

+ + +The Tape Coordinator assigns a task ID number to each operation it +performs. The number is distinct from the job ID number assigned by the +backup command interpreter in interactive mode (which is discussed +in Using Interactive and Regular Command Mode). The Tape Coordinator reports the task ID number in +its onscreen trace and in the messages that it writes to its log and error +files. To view the task ID numbers of a Tape Coordinator's running +or pending operations, issue the backup status command. + + + +

To start a Tape Coordinator process

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file of the cell in which the Tape +Coordinator is to access volume data and the Backup Database. If +necessary, issue the bos listusers command, which is fully +described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Alternately, you can log into a file server machine as the local superuser +root in Step 3. +
Verify that you can write to the Tape Coordinator's log and error +files in the local /usr/afs/backup directory (the +TE_device_name and TL_device_name +files). If the log and error files do not already exist, you must be +able to insert and write to files in the /usr/afs/backup +directory. +
Open a connection (using a command such as telnet or +rlogin) to the Tape Coordinator machine that drives the tape +device, or whose local disk houses the backup data file. The Tape +Coordinator uses a devoted connection or window that must remain open for the +Tape Coordinator to accept requests and while it is executing them. +
If you plan to include the -localauth flag to the +butc command in the next step, log in as the local superuser +root. +
Issue the butc command to start the Tape +Coordinator. You can include either, but not both, of the +-localauth and -cell options, as discussed in Performing Backup Operations as the Local Superuser Root or in a Foreign Cell. +
```
   % butc [<port offset>]  [-debuglevel <trace level>]  \
+          [-cell <cellname>] [-noautoquery] [-localauth]
+
```
+
where +
+
butc +
Must be typed in full. +
port offset +
Specifies the Tape Coordinator's port offset number. You must +provide this argument unless the default value of 0 (zero) is +appropriate. +
-debuglevel +
Specifies the type of trace messages that the Tape Coordinator writes to +the standard output stream (stdout). Provide one of the following three +values, or omit this argument to display the default type of messages +(equivalent to setting a value of 0 [zero]): +
- 0: The Tape Coordinator generates only the minimum number +of messages necessary to communicate with the backup operator, including +prompts for insertion of additional tapes and messages that indicate errors or +the beginning or completion of operations. +
- 1: In addition to the messages displayed at level +0, the Tape Coordinator displays the name of each volume being +dumped or restored. +
- 2: In addition to the messages displayed at levels +0 and 1, the Tape Coordinator displays all of the +messages it is also writing to its log file +(/usr/afs/backup/TL_device_name). +
+
cellname +
Names the cell in which to perform the backup operations (the cell where +the relevant volumes reside and the Backup Server process is running). +If you omit this argument, the Tape Coordinator uses its home cell, as defined +in the local /usr/vice/etc/ThisCell file. Do not combine +this argument with the -localauth flag. +
-noautoquery +
Disables the Tape Coordinator's prompt for the first tape it needs +for each operation. For a description of the advantages and +consequences of including this flag, see Eliminating the Search or Prompt for the Initial Tape. +
-localauth +
Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The butc process +presents it to the Backup Server, Volume Server, and VL Server during mutual +authentication. You must be logged into a file server machine as the +local superuser root to include this flag, and cannot combine it +with the -cell argument. +
+

+ +

To stop a Tape Coordinator process

Enter an interrupt signal such as <Ctrl-c> over the +dedicated connection to the Tape Coordinator. +

+ + + +

To check the status of a Tape Coordinator process

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the backup status command. +
```
   % backup status [<TC port offset>]
+
```
+
where +
+
st +
Is the shortest acceptable abbreviation of status. +
TC port offset +
Specifies the Tape Coordinator's port offset number. You must +provide this argument unless the default value of 0 (zero) is +appropriate. +
+

The following message indicates that the Tape Coordinator is not currently +performing an operation: +

   Tape coordinator is idle
+

Otherwise, the output includes a message of the following format for each +running or pending operation: +

   Task task_ID:  operation:   status
+

where +

task_ID +

Is a task identification number assigned by the Tape Coordinator. +It begins with the Tape Coordinator's port offset number. +

operation +

Identifies the operation the Tape Coordinator is performing, which is +initiated by the indicated command: +

Dump (the backup dump command) +
Restore (the backup diskrestore, backup +volrestore, or backup volsetrestore commands) +
Labeltape (the backup labeltape command) +
Scantape (the backup scantape command) +
SaveDb (the backup savedb command) +
RestoreDb (the backup restoredb command) +

status +

Indicates the job's current status in one of the following +messages. +

number Kbytes transferred, volume volume_name +: For a running dump operation, indicates the number of kilobytes copied to +tape or a backup data file so far, and the volume currently being +dumped. +
number Kbytes, restore.volume +: For a running restore operation, indicates the number of kilobytes copied +into AFS from a tape or a backup data file so far. +
[abort requested] +: The (backup) kill command was issued, but the termination +signal has yet to reach the Tape Coordinator. +
[abort sent] +: The operation is canceled by the (backup) kill command. +Once the Backup System removes an operation from the queue or stops it from +running, it no longer appears at all in the output from the command. +
[butc contact lost] +: The backup command interpreter cannot reach the Tape +Coordinator. The message can mean either that the Tape Coordinator +handling the operation was terminated or failed while the operation was +running, or that the connection to the Tape Coordinator timed out. +
[done] +: The Tape Coordinator has finished the operation. +
[drive wait] +: The operation is waiting for the specified tape drive to become +free. +
[operator wait] +: The Tape Coordinator is waiting for the backup operator to insert a tape +in the drive. +

If the Tape Coordinator is communicating with an XBSA server (a third-party +backup utility that implements the Open Group's Backup Service API +[XBSA]), the following message appears last in the output: +

   XBSA_program Tape coordinator
+

where XBSA_program is the name of the XBSA-compliant +program. +

Backing Up Data

+ + + + + + + + + + + + +

This section explains how to use the backup dump command to back +up AFS data to tape or to a backup data file. The instructions assume +that you understand Backup System concepts and have already configured the +Backup System according to the instructions in Configuring the AFS Backup System. Specifically, you must already have: +

Decided whether to dump data to tape or to a backup data file, and +configured the Tape Coordinator machine and Tape Coordinator process +appropriately. See Configuring Tape Coordinator Machines and Tape Devices and Dumping Data to a Backup Data File. +
Defined a volume set that includes the volumes you want to dump +together. See Defining and Displaying Volume Sets and Volume Entries. +
Defined the dump level in the dump hierarchy at which you want to dump the +volume set. If it is an incremental dump level, you must have +previously created a dump at its parent level. See Defining and Displaying the Dump Hierarchy. +
Created a device configuration file. Such a file is required for +each tape stacker, jukebox device, or backup data file. You can also +use it to configure the Backup System's automation features. See Automating and Increasing the Efficiency of the Backup Process. +

The most basic way to perform a dump operation is to create an initial dump +of a single volume set as soon as the appropriate Tape Coordinator is +available, by providing only the required arguments to the backup +dump command. Instructions appear in To create a dump. The command has several optional arguments that +you can use to increase the efficiency and flexibility of your backup +procedures: +

To append a dump to the end of a set of tapes that already contains other +dumps, include the -append argument. Otherwise, the Backup +System creates an initial dump. Appending dumps enables you to use a +tape's full capacity and has other potentially useful features. +For a discussion, see Appending Dumps to an Existing Dump Set. +
To schedule one or more dump operations to run at a future time, include +the -at argument. For a discussion and instructions, see Scheduling Dumps. +
To initiate a number of dump operations with a single backup +dump command, include the -file argument to name a file in +which you have listed the commands. For a discussion and instructions, +see Appending Dumps to an Existing Dump Set and Scheduling Dumps. +
To generate a list of the volumes to be included in a dump, without +actually dumping them, combine the -n flag with the other arguments +to be used on the actual command. +

Making Backup Operations More Efficient

+ +

There are several ways to make dump operations more efficient, less prone +to error, and less disruptive to your users. Several of them also +simplify the process of restoring data if that becomes necessary. +

It is best not to dump the read/write or read-only version of a volume, +because no other users or processes can access a volume while it is being +dumped. Instead, shortly before the dump operation begins, create a +backup version of each volume to be dumped, and dump the backup +version. Creating a Backup version usually makes the source volume +unavailable for just a few moments (during which access attempts by other +processes are blocked but do not fail). To automate the creation of +backup volumes, you can create a cron process in the +/usr/afs/local/BosConfig file on one or more server machines, +setting its start time at a sufficient interval before the dump operation is +to begin. Include the -localauth argument to the vos +backup or vos backupsys command to enable it to run without +administrative tokens. For instructions, see To create and start a new process. +
The volume set, dump level, and Tape Coordinator port offset you specify +on the backup dump command line must be properly defined in the +Backup Database. The Backup System checks the database before beginning +a dump operation and halts the command immediately if any of the required +entities are missing. If necessary, use the indicated commands: +
- To display volume sets, use the backup listvolsets command as +described in To display volume sets and volume entries. +
- To display dump levels, use the backup listdumps command as +described in To display the dump hierarchy. +
- To display port offsets, use the backup listhosts command as +described in To display the list of configured Tape Coordinators. +
+
Ensure that a valid token corresponding to a privileged administrative +identity is available to the Backup System processes both when the backup +dump command is issued and when the dump operation actually runs (for a +complete description or the necessary privileges, see Granting Administrative Privilege to Backup Operators). This is a special concern for scheduled +dumps. One alternative is to run backup commands (or the +script that invokes them) and the butc command on server machines, +and to include the -localauth argument on the command. In +this case, the processes use the key with the highest key version number in +the local /usr/afs/etc/KeyFile file to construct a token that never +expires. Otherwise, you must use a method to renew tokens before they +expire, or grant tokens with long lifetimes. In either case, you must +protect against improper access to the tokens by securing the machines both +physically and against unauthorized network access. The protection +possibly needs to be even stronger than when a human operator is present +during the operations. +
Record tape capacity and filemark size values that are as accurate as +possible in the Tape Coordinator's /usr/afs/backup/tapeconfig +file and on the tape's label. For suggested values and a +description of what can happen when they are inaccurate, see Configuring the tapeconfig File. +
If an unattended dump requires multiple tapes, arrange to provide them by +properly configuring a tape stacker or jukebox and writing a tape-mounting +script to be invoked in the device's CFG_device_name +file. For instructions, see Invoking a Device's Tape Mounting and Unmounting Routines. +
You can configure any tape device or backup data file's +CFG_device_name file to take advantage of the Backup +System's automation features. See Automating and Increasing the Efficiency of the Backup Process. +
When you issue a backup command in regular (noninteractive) +mode, the command shell prompt does not return until the operation +completes. To avoid having to open additional connections, issue the +backup dump command in interactive mode, especially when including +the -at argument to schedule dump operations. +
An incremental dump proceeds most smoothly if there is a dump created at +the dump level immediately above the level you are using. If the Backup +System does not find a Backup Database record for a dump created at the +immediate parent level, it looks for a dump created at one level higher in the +hierarchy, continuing up to the full dump level if necessary. It +creates an incremental dump at the level one below the lowest valid parent +dump that it finds, or even creates a full dump if that is necessary. +This algorithm guarantees that the dump captures all data that has changed +since the last dump, but has a couple of disadvantages. First, the +Backup System's search through the database for a valid parent dump takes +extra time. Second, the subsequent pattern of dumps can be confusing to +a human operator who needs to restore data from them, because they were not +performed at the expected dump levels. +
The easiest way to guarantee that a dump exists at the immediate parent +level is always to perform dump operations on the predetermined +schedule. To check that the parent dump exists, you can issue the +backup dumpinfo command (as described in To display dump records) and search for it in the output. Alternatively, +issue the backup volinfo command (as described in To display a volume's dump history) for a volume that you believe is in the parent dump. +
Always use dump levels from the same hierarchy (levels that are +descendants of the same full level) when dumping a given volume set. +The result of alternating between levels from different hierarchies can be +confusing when you need to restore data or read dump records. It also +increases the chance that changed data is not captured in any dump, or is +backed up redundantly into more than one dump. +
Use permanent tape names rather than AFS tape names. You can make +permanent names more descriptive than is allowed by an AFS tape name's +strict format, and also bypass the name-checking step that the Backup System +performs by default when a tape has an AFS tape name only. You can also +configure the Tape Coordinator always to skip the check, however; for +instructions and a description of the acceptable format for AFS tape names, +see Eliminating the AFS Tape Name Check. +
If you write dumps to tape, restore operations are simplest if all of your +tape devices are compatible (can read the same type of tape, at the same +compression ratios, and so on). If you must use incompatible devices, +then at least use compatible devices for all dumps performed at dump levels +that are at the same depth in their respective hierarchies (compatible devices +for all dumps performed at a full dump level, compatible devices for all dumps +performed at a level 1 incremental dump level, and so on). The +-portoffset argument to the backup diskrestore and +backup volsetrestore commands accepts multiple port offset numbers, +but uses the first listed port offset when restoring all full dumps, the +second port offset when restoring all level 1 dumps, and so on. If you +did not use compatible tape devices when creating dumps at the same depth in a +hierarchy, you must restore one volume at a time with the backup +volrestore command. +
In some cases, it makes sense to use a temporary volume set, +which exists only within the context of the interactive session in which it is +created and for which no record is created in the Backup Database. One +suitable situation is when dumping a volume to tape in preparation for +removing it permanently (perhaps because its owner is leaving the +cell). In this case, you can define a volume entry that includes only +the volume of interest without cluttering up the Backup Database with a volume +set record that you are using only once. +
Do not perform a dump operation when you know that there are network, +machine, or server process problems that can prevent the Backup System from +accessing volumes or the Volume Location Database (VLDB). Although the +Backup System automatically makes a number of repeated attempts to get to an +inaccessible volume, the dump operation takes extra time and in some cases +stops completely to prompt you for instructions on how to continue. +Furthermore, if the Backup System's last access attempt fails and the +volume is omitted from the dump, you must take extra steps to have it backed +up (namely, the steps described just following for a halted dump +operation). For a more complete description of how the Backup System +makes repeated access attempts, see How Your Configuration Choices Influence the Dump Process. +
Review the logs created by the Backup System as soon as possible after a +dump operation completes, particularly if it ran unattended. They name +any volumes that were not successfully backed up, among other problems. +The Backup Server writes to the /usr/afs/logs/BackupLog file on the +local disk of the database server machine, and you can use the bos +getlog command to read it remotely if you wish; for instructions, +see Displaying Server Process Log Files. The Tape Coordinator writes to two files in the +local /usr/afs/backup directory on the machine where it is +running: the TE_device_name file records errors, and +the TL_device_name file records both trace and error +messages. +
Avoid halting a dump operation (for instance, by issuing the (backup) +kill command in interactive mode), both because it introduces the +potential for confusion and because recovering from the interruption requires +extra effort. When a dump operation is interrupted, the volumes that +were backed up before the halt signal is received are complete on the tape or +in the backup data file, and are usable in restore operations. The +records in the Backup Database about the volumes' dump history accurately +show when and at which dump level they were backed up; to display the +records, use the backup volinfo command as described in To display a volume's dump history. +
However, there is no indication in the dump's Backup Database record +that volumes were omitted; to display the record, use the backup +dumpinfo command as described in To display dump records. You must choose one of the following methods for +dealing with the volumes that were not backed up before the dump operation +halted. (Actually, you must make the same decision if the dump +operation halts for reasons outside your control.) +
- You can take no action, waiting until the next regularly scheduled dump +operation to back them up. At that time, the Backup System +automatically dumps them at the appropriate level to guarantee that the dump +captures all of the data that changed since the volume was last dumped. +However, you are gambling that restoring the volume is not necessary before +the next dump operation. If restoration is necessary, you can restore +the volume only to its state at the time it was last included in a +dump--you have lost all changes made to the volume since that +time. +
- You can discard the entire dump and run the dump operation again. +To discard the dump, use the backup labeltape command to relabel +the tapes or backup data file, which automatically removes all associated +records from the Backup Database. For instructions, see Writing and Reading Tape Labels. If a long time has passed since the backup version +of the volumes was created, some of the source volumes have possibly +changed. If that seems likely, reissue the vos backup or +vos backupsys command on them before redoing the dump +operation. +
- You can create a new volume set that includes the missed volumes and dump +it at a full dump level (even if you specify an incremental dump level, the +Backup System uses the full dump level at the top of your specified +level's hierarchy, because it has never before backed up these volumes as +part of the new volume set). The next time you dump the original volume +set, the Backup System automatically dumps the missed volumes at the level one +below the level it used the last time it dumped the volumes as part of the +original volume set. +
+

How Your Configuration Choices Influence the Dump Process

+ +

This section provides an overview of the backup process, describing what +happens at each stage both by default and as a result of your configuration +choices, including the configuration instructions you include in the +device-specific CFG_device_name file. For the sake +of clarity, it tracks the progress of a single backup dump command +that creates an initial dump. For a discussion of the slight +differences in the procedure when you append or schedule dumps, see Appending Dumps to an Existing Dump Set or Scheduling Dumps. +

As a concrete example, the following description traces a dump of the +volume set user at the /weekly/mon/tues/wed dump +level. The user volume set has one volume entry that matches +the backup version of all user volumes: +

   .*    .*    user.*\.backup
+

The dump level belongs to the following dump hierarchy. +

   /weekly
+          /mon
+              /tues
+                   /wed
+                       /thurs
+                             /fri
+

You issue the butc command to start a Tape +Coordinator to handle the dump operation. The Tape Coordinator does not +have to be running when you issue the backup dump command, but must +be active in time to accept the list of volumes to be included in the dump, +when Step 3 is completed. To avoid coordination problems, it is +best to start the Tape Coordinator before issuing the backup dump +command. +
As the Tape Coordinator initializes, it reads the entry in its local +/usr/afs/backup/tapeconfig file for the port offset you specify on +the butc command line. The entry specifies the name of the +device to use, and the Tape Coordinator verifies that it can access it. +It also reads the device's configuration file, +/usr/afs/backup/CFG_device_name, if it exists. See +Step 6 for a description of how the instructions in the file +influence the dump operation. +
You issue the backup dump command, specifying a volume set, +dump level, and the same port offset number you specified on the +butc command in Step 1. The Backup System verifies that they have +correct Backup Database records and halts the operation with an error message +if they do not. +
If you issue the command in interactive mode, the Backup System assigns the +operation a job ID number, which you can use to check the operation's +status or halt it by using the (backup) jobs or (backup) +kill command, respectively. For instructions, see To display pending or running jobs in interactive mode and To cancel operations in interactive mode. +
The Backup System works with the VL Server to +generate a list of the volumes in the VLDB that match the name and location +criteria defined in the volume set's volume entries. If a volume +matches more than one volume entry, the Backup System ignores the duplicates +so that the dump includes only one copy of data from the volume. +
To reduce the number of times you need to switch tapes during a restore +operation, the Backup System sorts the volumes by server machine and +partition, and during the dump operation writes the data from all volumes +stored on a specific partition before moving to the next partition. +
As previously mentioned, it is best to back up backup volumes rather than +read/write volumes, to avoid blocking users' access to data during the +dump. To achieve this, you must explicitly include the +.backup suffix on the volume names in volume entry +definitions. For instructions, and to learn how to define volume +entries that match multiple volumes, see Defining and Displaying Volume Sets and Volume Entries. +
In the example, suppose that 50 volumes match the user volume +set criteria, including three called user.pat.backup, +user.terry.backup, and +user.smith.backup. +
The Backup System next scans the dump hierarchy for +the dump level you have specified on the backup dump command +line. If it is a full level, then in the current operation the Backup +System backs up all of the data in all of the volumes in the list obtained in +Step 3. +
If the dump level is incremental, the Backup System reads each +volume's dump history in the Backup Database to learn which of the parent +levels in its pathname was used when the volume was most recently backed up as +part of this volume set. In the usual case, it is the current dump +level's immediate parent level. +
An incremental dump of a volume includes only the data that changed since +the volume was included in the parent dump. To determine which data are +eligible, the Backup System uses the concept of a volume's clone +date. A read/write volume's clone date is when the Backup +System locks the volume before copying its contents into a dump. A +backup volume's clone date is the completion time of the operation that +created it by cloning its read/write source volume (the operation initiated by +a vos backup or vos backupsys command). A +read-only volume's clone date is the time of the release operation +(initiated by the vos release command) that completed most recently +before the dump operation. +
More precisely then, an incremental dump includes only data that have a +modification timestamp between the clone date of the volume included in the +parent dump (the parent clone date) and the clone date of the +volume to be included in the current dump (the current clone +date). +
There are some common exceptions to the general rule that a volume's +parent dump is the dump created at the immediate parent level: +
- The volume did not exist at all at the time of the last dump. In +this case, the Backup System automatically does a full dump of it. +
- The volume did not match the volume set's name and location criteria +at the time of the last dump. In this case, the Backup System +automatically does a full dump of it, even if it was backed up recently (fully +or incrementally) as part of another volume set. This redundancy is an +argument for defining volume entries in terms of names rather than locations, +particularly if you move volumes frequently. +
- The volume was not included in the dump at the immediate parent level for +some reason (perhaps a process, machine, or network access prevented the +Backup System from accessing it). In this case, the Backup System sets +the clone date to the time of the last dump operation that included the +volume. If the volume was not included in a dump performed at any of +the levels in the current level's pathname, the Backup System does a full +dump of it. +
+
In the example, the current dump level is +/weekly/mon/tues/wed. The +user.pat.backup and +user.terry.backup volumes were included in the dump +performed yesterday, Tuesday, at the /weekly/mon/tues level. +The Backup System uses as their parent clone date 3:00 +a.m. on Tuesday, which is when backup versions of them were +created just before Tuesday's dump operation. However, +Tuesday's dump did not include the +user.smith.backup volume for some reason. The +last time it was included in a dump was Monday, at the /weekly/mon +level. The Backup System uses a parent clone date of Monday at +2:47 a.m., which is when a backup version of the volume +was created just before the dump operation on Monday. +
If performing an incremental dump, the Backup System works with the Volume +Server to prepare a list of all of the files in each volume that have changed +(have modification timestamps) between the parent clone date and the current +clone date. The dump includes the complete contents of every such +file. If a file has not changed, the dump includes only a placeholder +stub for it. The dump also includes a copy of the complete directory +structure in the volume, whether or not it has changed since the previous +dump. +
If none of the data in the volume has changed since the last dump, the +Backup System omits the volume completely. It generates the following +message in the Tape Coordinator window and log files: +
```
   Volume volume_name (volume_ID) not dumped - has not been modified 
+      since last dump.
+
```
+
The Tape Coordinator prepares to back up the +data. If there is a CFG_device_name file, the Tape +Coordinator already read it in Step 1. The following list describes how the instructions in +the file guide the Tape Coordinator's behavior at this point: +
+
FILE +
If this instruction is set to YES, the Tape Coordinator writes +data to a backup data file. The device_name field in the +tapeconfig file must also specify a filename for the dump to work +properly. For further discussion and instructions on configuring a +backup data file, see Dumping Data to a Backup Data File. +
If it is set to NO or does not appear in the file, the Tape +Coordinator writes to a tape device. +
MOUNT and UNMOUNT +
If there is a MOUNT instruction in the file, each time the Tape +Coordinator needs a new tape, it invokes the indicated script or program to +mount a tape in the device's tape drive. There must be a +MOUNT instruction if you want to utilize a tape stacker or +jukebox's ability to switch between tapes automatically. If there +is no MOUNT instruction, the Tape Coordinator prompts the human +operator whenever it needs a tape. +
The AUTOQUERY instruction, which is described just following, +modifies the Tape Coordinator's tape acquisition procedure for the first +tape it needs in a dump operation. +
If there is an UNMOUNT instruction, then the Tape Coordinator +invokes the indicated script or program whenever it closes the tape +device. Not all tape devices have a separate tape unmounting routine, +in which case the UNMOUNT instruction is not necessary. For +more details on both instructions, see Invoking a Device's Tape Mounting and Unmounting Routines. +
AUTOQUERY +
If this instruction is set to NO, the Tape Coordinator assumes +that the first tape needed for the dump operation is already in the tape +drive. It does not use its usual tape acquisition procedure as +described in the preceding discussion of the MOUNT +instruction. You can achieve the same effect by including the +-noautoquery flag to the butc command. +
If this instruction is absent or set to YES, the Tape +Coordinator uses its usual tape acquisition procedure even for the first +tape. For more details, see Eliminating the Search or Prompt for the Initial Tape. +
BUFFERSIZE +
If this instruction appears in the file, the Tape Coordinator sets its +buffer size to the specified value rather than using the default buffer size +of 16 KB. For further discussion, see Setting the Memory Buffer Size to Promote Tape Streaming. +
+
If there is no CFG_device_name file, the Tape +Coordinator writes data to a tape device and prompts the human operator each +time it needs a tape (the only exception being the first tape if you include +the -noautoquery flag to the butc command). +
The Tape Coordinator opens either a tape drive or +backup data file at this point, as directed by the instructions in the +CFG_device_name file (described in Step 6). The instructions also determine whether it +invokes a mount script or prompts the operator. In Step 1 the Tape Coordinator read in the device's capacity and +filemark size from the tapeconfig file. It now reads the +same values from the tape or backup data file's magnetic label, and +overwrites the tapeconfig values if there is a difference. +
If creating an initial dump (as in the current example) and there is no +permanent name on the label, the Tape Coordinator next checks that the AFS +tape name has one of the three acceptable formats. If not, it rejects +the tape and you must use the backup labeltape command to write an +acceptable name. You can bypass this name-checking step by including +the NAME_CHECK NO instruction in the +CFG_device_name file. For discussion and a list of +the acceptable AFS tape name values, see Eliminating the AFS Tape Name Check. +
For an initial dump, the Tape Coordinator starts writing +at the beginning of the tape or backup dump file, overwriting any existing +data. To prevent inappropriate overwriting, the Backup System first +checks the Backup Database for any dump records associated with the name +(permanent or AFS tape name) on the tape or backup dump file's +label. It refuses to write to a backup data file that has unexpired +dumps in it, or to a tape that belongs to a dump set with any unexpired +dumps. To recycle a file or tape before all dumps have expired, you +must use the backup labeltape command to relabel it. Doing +so removes the Backup Database records of all dumps in the file or on all +tapes in the dump set, which makes it impossible to restore data from any of +the tapes. For more information on expiration dates, see Defining Expiration Dates. +
The Tape Coordinator also checks for two other types of inappropriate tape +reuse. The tape cannot already have data on it that belongs to the dump +currently being performed, because that implies that the previous tape is +still in the drive, or you have mistakenly reinserted it. The Tape +Coordinator generates the following message and attempts to obtain another +tape: +
```
   Can't overwrite tape containing the dump in progress
+
```
+
The tape cannot contain data from a parent dump of the current +(incremental) dump, because overwriting a parent dump makes it impossible to +restore data from the current dump. The Tape Coordinator generates the +following message and attempts to obtain another tape: +
```
   Can't overwrite the parent dump parent_name (parent_dump_ID)
+
```
+
The Tape Coordinator now writes data to the tape or backup +data file. It uses the capacity and filemark size it obtained in Step 7 as it tracks how much more space is available, automatically +using its tape acquisition procedure if the dump is not finished when it +reaches the end of the tape. For a more detailed description, and a +discussion of what happens if the Tape Coordinator reaches the physical +end-of-tape unexpectedly, see Configuring the tapeconfig File. Similarly, for instructions on configuring a backup +data file to optimize recovery from unexpectedly running out of space, see +Step 6 in the instructions in Dumping Data to a Backup Data File. +
If the Tape Coordinator cannot access a volume during the dump (perhaps +because of a server process, machine, or network outage), it skips the volume +and continues dumping all volumes that it can access. It generates an +error message in the Tape Coordinator window and log file about the omitted +volume. It generates a similar message if it discovers that a backup +volume has not been recloned since the previous dump operation (that is, that +the volume's current clone date is the same as its parent clone +date): +
```
   Volume volume_name (volume_ID) not dumped - has not been re-cloned 
+       since last dump.
+
```
+
After completing a first pass through all of the volumes, it attempts to +dump each omitted volume again. It first checks to see if the reason +that the volume was inaccessible during the first pass is that it has been +moved since the VL Server generated the list of volumes to dump in Step 3. If so, it dumps the volume from its new site. +If the second attempt to access a volume also fails, the Tape Coordinator it +generates the following message, prompting you for instruction on how to +proceed: +
```
   Dump of volume volume_name (volume_ID) failed
+   Please select action to be taken for this volume.
+      r - retry, try dumping this volume again
+      o - omit, this volume from this dump
+      a - abort, the entire dump
+
```
+
To increase the automation of the dump process, you can include the +ASK NO instruction in the CFG_device_name file +to suppress this prompt and have the Tape Coordinator automatically omit the +volume from the dump. +
If you are tracking the dump as it happens, the prompt enables you to take +corrective action. If the volume has not been recloned, you can issue +the vos backup command. If the volume is inaccessible, you +can investigate and attempt to resolve the cause. + + + + + +
If the tape or backup data file does not already have an AFS tape name, +the Backup System constructs the appropriate one and records it on the label +and in the Backup Database. It also assigns a dump name and ID number +to the dump and records them in dump record that it creates in the Backup +Database. For details on tape and dump names, see Dump Names and Tape Names. For instructions on displaying dump records or a +volume's dump history, or scanning the contents of a tape, see Displaying Backup Dump Records. +

Appending Dumps to an Existing Dump Set

+ +

The AFS Backup System enables you to append dumps to the end of the final +tape in a dump set by including the -append flag to the backup +dump command. Appending dumps improves Backup System automation +and efficiency in several ways: +

It maximizes use of a tape's capacity. An initial dump must +always start on a new tape, but does not necessarily extend to the end of the +final tape in the dump set. You can fill up the unused tape by +appending one or more dumps. +
It can reduce the number of tapes and tape changes needed to complete a +dump operation. Rather than performing a series of initial dumps first, +instead begin with an initial dump and follow it immediately with several +appended dumps. In this way you can write all dumps in the series to +the same tape (assuming the tape is large enough to accommodate them +all). If, in contrast, you perform all of the initial dumps first, each +must begin on a new tape and you must switch tapes again if you then want to +append dumps. +
You can either issue the appropriate series of backup dump +commands at the interactive backup> prompt, or record them in a +file that you then name with the -file argument to the backup +dump command. Appending dumps in this way enables you to run +multiple unattended backup operations even without a tape stacker or jukebox, +if all of the dumps fit on one tape. +
It can reduce the number of tape changes during a restore +operation. For example, if you append all of the incremental dumps of a +volume set to tapes in one dump set, then restoring a volume from the volume +set requires a minimum number of tape changes. It is best not to append +incremental dumps to a tape that contains the parent full dump, however: +if the tape is lost or damaged, you lose all of the data from the +volume. +
Although it can be efficient to group together appended dumps that are +related, the Backup System does not require any relationship between the +appended dumps on a tape or in a dump set. +

When writing an appended dump, the Backup System performs most of the steps +described in How Your Configuration Choices Influence the Dump Process. Appended dumps do not have to be related to one +another or the initial dump, so it skips Step 7: there is no need to check that the AFS tape name +reflects the volume set and dump level names in this case. It also +skips Step 8. Because it is not overwriting any existing data on +the tape, it does not need to check the expiration dates of existing dumps on +the tape or in the file. Then in Step 9 the Tape Coordinator scans to the end of the last dump on +the tape or in the backup data file before it begins writing data. +

The Backup System imposes the following conditions on appended dumps: +

If writing to tape, the Tape Coordinator checks that it is the final one +in a dump set for which there are complete and valid tape and dump records in +the Backup Database. If not, it rejects the tape and requests an +acceptable one. If you believe the tape has valid data on it, you can +reconstruct the Backup Database dump records for it by using the +-dbadd argument to the backup scantape command as +instructed in To scan the contents of a tape. +
The most recent dump on the tape or in the backup data file must have +completed successfully. +
The dump set to which the tape or file belongs must begin with an initial +dump that is recorded in the Backup Database. If there are no dumps on +the current tape, then the Backup System treats the dump operation as an +initial dump and imposes the relevant requirements (for example, checks the +AFS tape name if appropriate). +

As you append dumps, keep in mind that all of a dump set's dump and +tape records in the Backup Database are indexed to the initial dump. If +you want to delete an appended dump's record, you must delete the initial +dump record, and doing so erases the records of all dumps in the dump +set. Without those records, you cannot restore any of the data in the +dump set. +

Similarly, all of the dumps in a dump set must expire before you can +recycle (write a new initial dump to) any of the tapes in a dump set. +Do not append a dump if its expiration date is later than the date on which +you want to recycle any of the tapes in its dump set. To recycle a tape +before the last expiration date, you must delete the initial dump's +record from the Backup Database. Either use the backup +labeltape command to relabel the tape as instructed in To label a tape, or use the backup deletedump command +to delete the record directly as instructed in To delete dump records from the Backup Database. +

Although in theory you can append as many dumps as you wish, it generally +makes sense to limit the number of tapes in a dump set (for example, to five), +for these reasons: +

If an unreadable spot develops on one of the tapes in a dump set, it can +prevent the Tape Coordinator from scanning the tape as part of a backup +scantape operation you use to reconstruct Backup Database +records. The Tape Coordinator can almost always scan the tape +successfully up to the point of damage and can usually skip past minor +damage. A scanning operation can start on any tape in a dump set, so +damage on one tape does not prevent scanning of the others in the dump +set. However, you can scan only the tapes that precede the damaged one +in the dump set or the ones that follow the damaged one, but not both. +(For more information on using tapes to reconstruct the information in the +Backup Database, see To scan the contents of a tape.) +
An unreadable bad spot can also prevent you from restoring a volume +completely, because restore operations must begin with the full dump and +continue with each incremental dump in order. If you cannot restore a +specific dump, you cannot restore any data from later incremental +dumps. +
If you decide in the future to archive one or more dumps, then you must +archive the entire set of tapes that constitute the dump set, rather than just +the ones that contain the data of interest. This wastes both tape and +archive storage space. For more information on archiving, see Archiving Tapes. +

Scheduling Dumps

By default, the Backup System starts executing a dump +operation as soon as you enter the backup dump command, and the +Tape Coordinator begins writing data as soon as it is not busy and the list of +files to write is available. You can, however, schedule a dump +operation to begin at a specific later time: +

To schedule a single dump operation, include the -at argument +to specify its start time. +
To schedule multiple dump operations, list the operations in a file named +by the -file argument and use the -at argument to +specify when the backup command interpreter reads the file. +If you omit the -at argument, the command interpreter reads the +file immediately, which does not count as scheduling, but does allow you to +initiate multiple dump operations in a single command. Do not combine +the -file argument with the -volumeset, +-dump, -portoffset, -append, or -n +options. +
For file-formatting instructions, see the description of the +-file argument in Step 7 of To create a dump. +

The Backup System performs initial and appended dumps in the same manner +whether they are scheduled or begin running as soon as you issue the +backup dump command. The only difference is that the +requirements for successful execution hold both at the time you issue the +command and when the Backup System actually begins running it. All +required Backup Database entries for volume sets, dump levels, and port +offsets, and all dump and tape records must exist at both times. +Perhaps more importantly, the required administrative tokens must be available +at both times. See Making Backup Operations More Efficient. +

To create a dump

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If the Tape Coordinator for the tape device that is to perform the +operation is not already running, open a connection to the appropriate Tape +Coordinator machine and issue the butc command, for which complete +instructions appear in To start a Tape Coordinator process. +
```
   % butc [<port offset>] [-noautoquery]
+
```
+
If using a tape device, insert the tape. +
Issue the backup command to enter interactive mode. +
```
   % backup
+
```
+
Decide which volume set and dump level to use. If necessary, issue +the backup listvolsets and backup listdumps commands to +display the existing volume sets and dump levels. For complete +instructions and a description of the output, see To display volume sets and volume entries and To display the dump hierarchy. +
```
   backup> listvolsets  [<volume set name>]
+   backup> listdumps
+
```
+
If you want to use a temporary volume set, you must create it during the +current interactive session. This can be useful if you are dumping a +volume to tape in preparation for removing it permanently (perhaps because its +owner is leaving the cell). In this case, you can define a volume entry +that includes only the volume of interest without cluttering up the Backup +Database with a volume set record that you are using only once. +Complete instructions appear in Defining and Displaying Volume Sets and Volume Entries. +
```
   backup>  addvolset <volume set name> -temporary
+   backup> addvolentry  -name <volume set name>  \
+                        -server <machine name>  \
+                        -partition <partition name>  \
+                        -volumes <volume name (regular expression)>
+
```
+
If you are creating an initial dump and writing to a tape or backup data +file that does not have a permanent name, its AFS tape name must satisfy the +Backup System's format requirements as described in Eliminating the AFS Tape Name Check. If necessary, use the backup readlabel +command to display the label and the backup labeltape command to +change the names, as instructed in Writing and Reading Tape Labels. You must also relabel a tape if you want to +overwrite it and it is part of a dump set that includes any unexpired dumps, +though this is not recommended. For a discussion of the appropriate way +to recycle tapes, see Creating a Tape Recycling Schedule. + + +

Issue the backup dump command to dump the +volume set. +

To create one initial dump, provide only the volume set name, dump level +name, and port offset (if not zero). +
To create one appended dump, add the -append flag. +
To schedule a single initial or appended dump, add the -at +argument. +
To initiate multiple dump operations, record the appropriate commands in a +file and name it with the -file argument. Do not combine +this argument with options other than the -at argument. +

   backup> dump <volume set name> <dump level name> [<TC port offset>]   \
+                [-at <Date/time to start dump>⁺]  \
+                [-append]  [-n] [-file <load file>]
+

where +

dump +

Must be typed in full. +

volume set name +

Names the volume set to dump. +

dump level name +

Specifies the complete pathname of the dump level at which to dump the +volume set. +

TC port offset +

Specifies the port offset number of the Tape Coordinator process that is +handling the operation. You must provide this argument unless the +default value of 0 (zero) is appropriate. +

-at +

Specifies the date and time in the future at which to run the command, or +to read the file named by the -file argument. Provide a +value in the format mm/dd/yyyy +[hh:MM], where the month (mm), day +(dd), and year (yyyy) are required. 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 Backup System automatically reduces any later +date to the maximum value in 2038. +

The hour and minutes (hh:MM) are optional, but if +provided must be in 24-hour format (for example, the value +14:36 represents 2:36 p.m.). If +you omit them, the time defaults to midnight (00:00 hours). +

As an example, the value 04/23/1999 20:20 schedules the +command for 8:20 p.m. on 23 April 1999. +
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. +
+

-append +

Creates an appended dump by scanning to the end of the data from one or +more previous dump operations that it finds on the tape or in the backup data +file. +

-n +

Displays the names of all volumes to be included in the indicated dump, +without actually writing data to tape or the backup data file. Combine +this flag with the arguments you plan to use on the actual command, but not +with the -file argument. +

-file +

Specifies the local disk or AFS pathname of a file containing +backup commands. The Backup System reads the file +immediately, or at the time specified by the -at argument if it is +provided. A partial pathname is interpreted relative to the current +working directory. +

Place each backup dump command on its own line in the indicated +file, using the same syntax as for the command line, but without the word +backup at the start of the line. Each command must include +the volume set name and dump level name arguments plus the +TC port offset argument if the default value of zero is not +appropriate. Commands in the file can also include any of the +backup dump command's optional arguments, including the +-at argument (which must specify a date and time later than the +date and time at which the Backup System reads the file). +

If you did not include the -noautoquery flag when you issued +the butc command, or if the device's +CFG_device_name configuration file includes the +instruction AUTOQUERY YES, then the Tape Coordinator prompts you to +place the tape in the device's drive. You have already done so, +but you must now press <Return> to indicate that the tape is +ready for labeling. +
If more than one tape is required, you must either include the +MOUNT instruction in the CFG_device_name file +and stock the corresponding stacker or jukebox with tapes, or remain at the +console to respond to the Tape Coordinator's prompts for subsequent +tapes. +
After the dump operation completes, review the Backup System's log +files to check for errors. Use the bos getlog command as +instructed in Displaying Server Process Log Files to read the /usr/afs/logs/BackupLog file, and a +text editor on the Tape Coordinator machine to read the +TE_device_name and TL_device_name +files in the local /usr/afs/backup directory. +
It is also a good idea to record the tape name and dump ID number on the +exterior label of each tape. +

Displaying Backup Dump Records

The backup command suite includes three commands +for displaying information about data you have backed up: +

To display information about one or more dump operations, such as the date +it was performed and the number of volumes included, use the backup +dumpinfo command as described in To display dump records. You can display a detailed record of a single dump +or more condensed records for a certain number of dumps, starting with the +most recent and going back in time. You can specify the number of dumps +or accept the default of 10. +
To display a volume's dump history, use the backup volinfo +command as described in To display a volume's dump history. +
To display information extracted from a tape or backup data file about the +volumes it includes, use the backup scantape command. To +create new dump and tape records in the Backup Database derived from the tape +and dump labels, add the -dbadd flag. For instructions, see To scan the contents of a tape. +

+ + + + + + + +

To display dump records

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the backup dumpinfo command to list information about +dumps recorded in the Backup Database. +
```
   % backup dumpinfo [-ndumps <no. of dumps>]  [-id <dump id>]  [-verbose]
+
```
+
where +
+
dump +
Is the shortest acceptable abbreviation of dumpinfo. +
-ndumps +
Displays the Backup Database record for each of the specified number of +dumps, starting with the most recent and going back in time. If the +database contains fewer dumps than are requested, the output includes the +records for all existing dumps. Do not combine this argument with the +-id argument or -verbose flag; omit all three +options to display the records for the last 10 dumps. +
-id +
Specifies the dump ID number of a single dump for which to display the +Backup Database record. You must include the -id +switch. Do not combine this option with the -ndumps or +-verbose arguments; omit all three arguments to display the +records for the last 10 dumps. +
-verbose +
Provides more detailed information about the dump specified with the +-id argument, which must be provided along with it. Do not +combine this flag with the -ndumps option. +
+

If the -ndumps argument is provided, the output presents the +following information in table form, with a separate line for each dump: +

dumpid +

The dump ID number. +

parentid +

The dump ID number of the dump's parent dump. A value of +0 (zero) identifies a full dump. +

lv +

The depth in the dump hierarchy of the dump level used to create the +dump. A value of 0 (zero) identifies a full dump, in which +case the value in the parentid field is also 0. A +value of 1 or greater indicates an incremental dump made at the +corresponding level in the dump hierarchy. +

created +

The date and time at which the Backup System started the dump operation +that created the dump. +

nt +

The number of tapes that contain the data in the dump. A value of +0 (zero) indicates that the dump operation was terminated or +failed. Use the backup deletedump command to remove such +entries. +

nvols +

The number of volumes from which the dump includes data. If a +volume spans tapes, it is counted twice. A value of 0 (zero) +indicates that the dump operation was terminated or failed; the value in +the nt field is also 0 in this case. +

dump name +

The dump name in the form +

   volume_set_name.dump_level_name (initial_dump_ID)
+   
+

where volume_set_name is the name of the volume set, and +dump_level_name is the last element in the dump level pathname at +which the volume set was dumped. +

The initial_dump_ID, if displayed, is the dump ID of the initial +dump in the dump set to which this dump belongs. If there is no value +in parentheses, the dump is the initial dump in a dump set that has no +appended dumps. +

If the -id argument is provided alone, the first line of output +begins with the string Dump and reports information for the entire +dump in the following fields: +

id +: The dump ID number. +
level +: The depth in the dump hierarchy of the dump level used to create the +dump. A value of 0 (zero) identifies a full dump. A +value of 1 (one) or greater indicates an incremental dump made at +the specified level in the dump hierarchy. +
volumes +: The number of volumes for which the dump includes data. +
created +: The date and time at which the dump operation began. +

If an XBSA server was the backup medium for the dump (rather than a tape +device or backup data file), the following line appears next: +

   Backup Service: XBSA_program: Server: hostname
+

where XBSA_program is the name of the XBSA-compliant program and +hostname is the name of the machine on which the program runs. +

Next the output includes an entry for each tape that houses volume data +from the dump. Following the string Tape, the first two +lines of each entry report information about that tape in the following +fields: +

name +: The tape's permanent name if it has one, or its AFS tape name +otherwise, and its tape ID number in parentheses. +
nVolumes +: The number of volumes for which this tape includes dump data. +
created +: The date and time at which the Tape Coordinator began writing data to this +tape. +

Following another blank line, the tape-specific information concludes with +a table that includes a line for each volume dump on the tape. The +information appears in columns with the following headings: +

Pos +: The relative position of each volume in this tape or file. On a +tape, the counter begins at position 2 (the tape label occupies position 1), +and increments by one for each volume. For volumes in a backup data +file, the position numbers start with 1 and do not usually increment only by +one, because each is the ordinal of the 16 KB offset in the file at which the +volume's data begins. The difference between the position numbers +therefore indicates how many 16 KB blocks each volume's data +occupies. For example, if the second volume is at position 5 and the +third volume in the list is at position 9, that means that the dump of the +second volume occupies 64 KB (four 16-KB blocks) of space in the file. +
Clone time +: For a backup or read-only volume, the time at which it was cloned from its +read/write source. For a Read/Write volume, it is the same as the dump +creation date reported on the first line of the output. +
Nbytes +: The number of bytes of data in the dump of the volume. +
Volume +: The volume name, complete with .backup or +.readonly extension if appropriate. +

If both the -id and -verbose options are provided, +the output is divided into several sections: +

The first section, headed by the underlined string Dump, +includes information about the entire dump. The fields labeled +id, level, created, and nVolumes +report the same values (though in a different order) as appear on the first +line of output when the -id argument is provided by itself. +Other fields of potential interest to the backup operator are: +
+
Group id +
The dump's group ID number, which is recorded in the +dump's Backup Database record if the GROUPID instruction +appears in the Tape Coordinator's +/usr/afs/backup/CFG_tcid file when the dump is created. +
maxTapes +
The number of tapes that contain the dump set to which this dump +belongs. +
Start Tape Seq +
The ordinal of the tape on which this dump begins in the set of tapes that +contain the dump set. +
+
For each tape that contains data from this dump, there follows a section +headed by the underlined string Tape. The fields labeled +name, written, and nVolumes report the same +values (though in a different order) as appear on the second and third lines +of output when the -id argument is provided by itself. Other +fields of potential interest to the backup operator are: +
+
expires +
The date and time when this tape can be recycled, because all dumps it +contains have expired. +
nMBytes Data and nBytes Data +
Summed together, these fields represent the total amount of dumped data +actually from volumes (as opposed to labels, filemarks, and other +markers). +
KBytes Tape Used +
The number of kilobytes of tape (or disk space, for a backup data file) +used to store the dump data. It is generally larger than the sum of the +values in the nMBytes Data and nBytes Data fields, +because it includes the space required for the label, file marks and other +markers, and because the Backup System writes data at 16 KB offsets, even if +the data in a given block doesn't fill the entire 16 KB. +
+
For each volume on a given tape, there follows a section headed by the +underlined string Volume. The fields labeled +name, position, clone, and nBytes +report the same values (though in a different order) as appear in the table +that lists the volumes in each tape when the -id argument is +provided by itself. Other fields of potential interest to the backup +operator are: +
+
id +
The volume ID. +
tape +
The name of the tape containing this volume data. +
+

The following example command displays the Backup Database records for the +five most recent dump operations. +

   % backup dump 5
+      dumpid   parentid lv created          nt nvols dump name
+   924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
+   924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
+   924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
+   924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
+   925033000          0 0  04/25/1999 05:36  2    73 sys.week
+

+ + + + +

To display a volume's dump history

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the backup volinfo command to display a volume's +dump history. +
```
   % backup volinfo <volume name>
+
```
+
where +
+
voli +
Is the shortest acceptable abbreviation of volinfo. +
volume name +
Names the volume for which to display the dump history. If you +dumped the backup or read-only version of the volume, include the +.backup or .readonly extension. +
+

The output includes a line for each Backup Database dump record that +mentions the specified volume, order from most to least recent. The +output for each record appears in a table with six columns: +

dumpID +: The dump ID of the dump that includes the volume. +
lvl +: The depth in the dump hierarchy of the dump level at which the volume was +dumped. A value of 0 indicates a full dump. A value +of 1 or greater indicates an incremental dump made at the specified +depth in the dump hierarchy. +
parentid +: The dump ID of the dump's parent dump. A value of 0 +indicates a full dump, which has no parent; in this case, the value in +the lvl column is also 0. +
creation date +: The date and time at which the Backup System started the dump operation +that created the dump. +
clone date +: For a backup or read-only volume, the time at which it was cloned from its +read/write source. For a read/write volume, the same as the value in +the creation date field. +
tape name +: The name of the tape containing the dump: either the permanent tape +name, or an AFS tape name in the format +volume_set_name.dump_level_name.tape_index +where volume_set_name is the name of the volume set associated with +the initial dump in the dump set of which this tape is a part; +dump_level_name is the name of the dump level at which the initial +dump was backed up; tape_index is the ordinal of the tape in +the dump set. Either type of name can be followed by a dump ID in +parentheses; if it appears, it is the dump ID of the initial dump in the +dump set to which this appended dump belongs. +

The following example shows part of the dump history of the backup volume +user.smith.backup: +

   % backup volinfo user.smith.backup
+   DumpID    lvl parentID  creation   date  clone date       tape name
+   924600000 1   924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
+   924514392 1   924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2 
+   924427600 0           0 04/18/1999 05:26 04/18/1999 04:58 user_full_6 
+       .     .      .         .       .       .      .         .
+       .     .      .         .       .       .      .         .
+

+ + + + + +

To scan the contents of a tape

Note:

The ability to scan a tape that is corrupted or damaged +depends on the extent of the damage and what type of data is corrupted. +The Backup System can almost always scan the tape successfully up to the point +of damage. If the damage is minor, the Backup System can usually skip +over it and scan the rest of the tape, but more major damage can prevent +further scanning. A scanning operation does not have to begin with the +first tape in a dump set, but the Backup System can process tapes only in +sequential order after the initial tape provided. Therefore, damage on +one tape does not prevent scanning of the others in the dump set, but it is +possible to scan either the tapes that precede the damaged one or the ones +that follow it, not both. +

If you use the -dbadd flag to scan information into the Backup +Database and the first tape you provide is not the first tape in the dump set, +the following restrictions apply: +

If the first data on the tape is a continuation of a volume that begins on +the previous (unscanned) tape in the dump set, the Backup System does not add +a record for that volume to the Backup Database. +
The Backup System must read the marker that indicates the start of an +appended dump to add database records for the volumes in it. If the +first volume on the tape belongs to an appended dump, but is not immediately +preceded by the appended-dump marker, the Backup System does not create a +Backup Database record for it or any subsequent volumes that belong to that +appended dump. +

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If the Tape Coordinator for the tape device that is to perform the +operation is not already running, open a connection to the appropriate Tape +Coordinator machine and issue the butc command, for which complete +instructions appear in To start a Tape Coordinator process. +
```
   % butc [<port offset>] [-noautoquery]
+
```
+
If scanning a tape, place it in the drive. +
(Optional) Issue the backup command to enter +interactive mode. +
```
   % backup
+
```
+ + +
Issue the backup scantape command to read the contents of the +tape. +
```
   backup> scantape [-dbadd] [-portoffset <TC port offset>]
+
```
+
where +
+
sc +
Is the shortest acceptable abbreviation of scantape. +
-dbadd +
Constructs dump and tape records from the tape and dump labels in the dump +and writes them into the Backup Database. +
TC port offset +
Specifies the port offset number of the Tape Coordinator process that is +handling the operation. You must provide this argument unless the +default value of 0 (zero) is appropriate. +
+
If you did not include the -noautoquery flag when you issued +the butc command, or the device's +CFG_device_name configuration file includes the +instruction AUTOQUERY YES instruction, then the Tape Coordinator +prompts you to place the tape in the device's drive. You have +already done so, but you must now press <Return> to indicate +that the tape is ready for reading. +

To terminate a tape scanning operation, use a termination signal such as +<Ctrl-c>, or issue the (backup) kill command in +interactive mode. It is best not to interrupt the scan if you included +the -dbadd argument. If the Backup System has already +written new records into the Backup Database, then you must remove them before +rerunning the scanning operation. If during the repeated scan operation +the Backup System finds that a record it needs to create already exists, it +halts the operation. +

For each dump on the tape, the output in the Tape Coordinator window +displays the dump label followed by an entry for each volume. There is +no output in the command window. The dump label has the same fields as +the tape label displayed by the backup readlabel command, as +described in Writing and Reading Tape Labels. Or see the IBM AFS Administration +Reference for a detailed description of the fields in the output. +

The following example shows the dump label and first volume entry on the +tape in the device that has port offset 2: +

   % backup scantape 2
+   -- Dump label --
+   tape name = monthly_guest
+   AFS tape name = guests.monthly.3
+   creationTime =  Mon Feb  1 04:06:40 1999
+   cell = abc.com
+   size = 2150000 Kbytes
+   dump path = /monthly
+   dump id = 917860000
+   useCount = 44
+   -- End of dump label --
+   -- volume --
+   volume name: user.guest10.backup
+   volume ID 1937573829
+   dumpSetName: guests.monthly
+   dumpID 917860000
+   level 0
+   parentID 0
+   endTime 0
+   clonedate Mon Feb  1 03:03:23 1999
+

Restoring and Recovering Data

+ + + + + + + + + + + + +

The purpose of making backups is to enable you to recover when data becomes +corrupted or is removed accidentally, returning the data to a coherent past +state. The AFS Backup System provides three commands that restore +varying numbers of volumes: +

To restore one or more volumes to a single site (partition on an AFS file +server machine), use the backup volrestore command. +
To restore one or more volumes that are defined as a volume set, each to a +specified site, use the backup volsetrestore command. +
To restore an entire partition (that is, all of the volumes that the VLDB +lists as resident on it), use the backup diskrestore +command. +

The commands are suited to different purposes because they vary in the +combinations of features they offer and in the requirements they +impose. To decide which is appropriate for a specific restore +operation, see the subsequent sections of this introduction: Using the backup volrestore Command, Using the backup diskrestore Command, and Using the backup volsetrestore Command. +

Making Restore Operations More Efficient

The following comments apply to all types of restore +operation: +

The Backup System begins by restoring the most recent full dump of a +volume. As it restores subsequent incremental dumps, it alters the data +in the full dump appropriately, essentially repeating the volume's change +history. The backup diskrestore and backup +volsetrestore commands always restore all incremental dumps, bringing a +volume to its state at the time of the most recent incremental dump. +You can use the backup volrestore command to return a volume to its +state at a specified time in the past, by not restoring the data from +incremental dumps performed after that time. +
The Backup System sets a restored volume's creation date to the date +and time of the restore operation. The creation date appears in the +Creation field of the output from the vos examine and +vos listvol commands. +
When identifying the volumes to restore, it is best to specify the base +(read/write) name. In this case, the Backup System searches the Backup +Database for the most recent dump set that includes data from either the +read/write or backup version of the volume, and restores dumps of that volume +starting with the most recent full dump. If you include the +.backup or .readonly extension on the +volume name, the Backup System restores dumps of that version only. If +it cannot find data dumped from that version, it does not perform the +restoration even if another version was dumped. +
All three restoration commands accept the -n option, which +generates a list of the volumes to be restored and the tapes or backup data +files that contain the necessary dumps, without actually restoring data to AFS +server partitions. This enables you to gather together the tapes before +beginning the restore operation, even preloading them into a stacker or +jukebox if you are using one. +
If you back up AFS data to tape, restoration is simplest if all of your +tape devices are compatible, meaning that they can read the same type of tape, +at the same compression ratios, and so on. (This suggestion also +appears in Making Backup Operations More Efficient, because by the time you need to restore data it is too late +to implement it.) You can still restore multiple volumes with a single +command even if data was backed up using incompatible devices, because the +-portoffset argument to all three restoration commands accepts +multiple values. However, the Backup System uses the first port offset +listed when restoring the full dump of each volume, the next port offset when +restoring the level 1 incremental dump of each volume, and so on. If +you did not use a compatible tape device when creating the full dump of every +volume (and at each incremental level too), you cannot restore multiple +volumes with a single command. You must use the backup +volrestore command to restore one volume at a time, or use the +backup volsetrestore command after defining volume sets that group +volumes according to the tape device used to dump them. +
During a restore operation, the Backup System uses instructions in the +relevant CFG_device_name configuration file in much the +same way as during a dump operation, as described in How Your Configuration Choices Influence the Dump Process. It uses the MOUNT, UNMOUNT, +AUTOQUERY, BUFFERSIZE, and FILE instructions +just as for a dump operation. A difference for the +BUFFERSIZE instruction is that the default buffer size overridden +by the instruction is 32 KB for restore operations rather than the 16 KB used +for dump operations. The Backup System does not use the +NAME_CHECK instruction at all during restore operations. The +ASK instruction controls whether the Backup System prompts you if +it cannot restore a volume for any reason. If the setting is +NO, it skips the problematic volume and restores as many of the +other volumes as possible. +
Do not perform a restore operation when you know that there are network, +machine, or server process problems that can prevent the Backup System from +accessing volumes or the VLDB. Although the Backup System automatically +makes a number of repeated attempts to restore a volume, the restore operation +takes extra time and in some cases stops completely to prompt you for +instructions on how to continue. +
Avoid halting a restore operation (for instance by issuing the +(backup) kill command in interactive mode). If a restore +operation is interrupted for any reason, including causes outside your +control, reissue the same restoration command as soon as is practical; if +an outage or other problem caused the operation to halt, do not continue until +the system returns to normal. +
Any volume that is completely restored when the operation halts is online +and usable, but very few volumes are likely to be in this state. When +restoring multiple volumes at once, the Backup System restores the full dump +of every volume before beginning the level 1 incremental restore for any of +them, and so on, completing the restore of every volume at a specific +incremental level before beginning to restore data from the next incremental +level. Unless a volume was dumped at fewer incremental levels than +others being restored as part of the same operation, it is unlikely to be +complete. +
It is even more dangerous to interrupt a restore operation if you are +overwriting the current contents of the volume. Depending on how far +the restore operation has progressed, it is possible that the volume is in +such an inconsistent state that the Backup System removes it entirely. +The data being restored is still available on tape or in the backup data file, +but you must take extra steps to re-create the volume. +

Using the backup volrestore Command

+ + + + + + +

The backup volrestore command is most appropriate when you need +to restore a few volumes to a single site (partition on a file server +machine). By default, it restores the volumes to their state at the +time of the most recent dump operation (this is termed a full +restore). You can also use the command to perform a +date-specific restore, which restores only the dumps (full and +incremental) performed before a specified date and time, leaving the volume in +the state it was in at the time of the final relevant incremental dump. +The backup diskrestore and backup volsetrestore commands +can only perform full restores. +

You can restore data into a new copy of each volume rather than overwriting +the current version, by including the -extension argument. +After mounting the new volume in the filespace, you can compare the contents +of the two and decide which to keep permanently. +

The following list summarizes how to combine the backup +volrestore command's arguments to restore a volume in different +ways: +

To perform a date-specific restore as described just previously, use the +-date argument to specify the date and optionally time. The +Backup System restores the most recent full dump and each subsequent +incremental dump for which the clone date of the volume included in the dump +is before the indicated date and time (for a definition of the clone date, see +Step 4 in How Your Configuration Choices Influence the Dump Process). You can combine this argument with +the -extension argument to place the date-specific restore in a new +volume. +
To move a volume to a new site as you overwrite its contents with the +restored data, use the -server and -partition arguments, +singly or in combination, to specify the new site rather than the current +site. The Backup System creates a new volume at that site, removes the +existing volume, and updates the site information in the volume's VLDB +entry. The volume's backup version is not removed automatically +from the original site, if it exists. Use the vos remove +command to remove it and the vos backup command to create a backup +version at the new site. +
To create a new volume to house the restored data, rather than overwriting +an existing volume, use the -extension argument. The Backup +System creates the new volume on the server and partition named by the +-server and -partition arguments, derives its name by +adding the extension to the name specified with the -volume +argument, and creates a new VLDB entry for it. The command does not +affect the existing volume in any way. However, if a volume with the +specified extension also already exists, the command overwrites it. To +make the contents of the new volume accessible, use the fs mkmount +command to mount it. You can then compare its contents to those of the +existing volume, to see which to retain permanently. +
To restore a volume that no longer exists on an AFS server partition, but +for which you have backed up data, specify the name of the new volume with the +-volume argument and use the -server and +-partition arguments to place it at the desired site. The +Backup System creates a new volume and new VLDB entry. +

+ + +

To restore volumes with the backup volrestore command

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If the Tape Coordinator for the tape device that is to perform the +operation is not already running, open a connection to the appropriate Tape +Coordinator machine and issue the butc command, for which complete +instructions appear in To start a Tape Coordinator process. +
```
   % butc [<port offset>] [-noautoquery]
+
```
+
Repeat the command for each Tape Coordinator if you are using more than one +tape device. +
If using a tape device, insert the tape. +
Issue the backup command to enter interactive mode. +
```
   % backup
+
```
+

Issue the backup volrestore command with the desired +arguments. +

   backup> volrestore <destination machine> <destination partition>  \ 
+                      -volume <volume(s) to restore>⁺  \
+                      [-extension <new volume name extension>]  \
+                      [-date <date from which to restore>]  \
+                      [-portoffset <TC port offsets>⁺] [-n]
+

where +

volr +

Is the shortest acceptable abbreviation of volrestore. +

destination machine +

Names the file server machine on which to restore each volume. It +does not have to be a volume's current site. +

destination partition +

Names the partition on which to restore each volume. It does not +have to be a volume's current site. +

-volume +

Names each volume to restore. It is best to provide the base +(read/write) name, for the reasons discussed in Making Restore Operations More Efficient. +

-extension +

Creates a new volume to house the restored data, with a name derived by +appending the specified string to each volume named by the -volume +extension. The Backup System preserves the contents of the existing +volume if it still exists. Do not use either of the +.readonly or .backup extensions, which are +reserved. The combination of base volume name and extension cannot +exceed 22 characters in length. If you want a period to separate the +extension from the name, specify it as the first character of the string (as +in .rst, for example). +

-date +

Specifies a date and optionally time; the restored volume includes +data from dumps performed before the date only. Provide a value in the +format mm/dd/yyyy +[hh:MM], where the required mm/dd/yyyy +portion indicates the month (mm), day (dd), and year +(yyyy), and the optional hh:MM portion indicates +the hour and minutes in 24-hour format (for example, the value +14:36 represents 2:36 p.m.). If +omitted, the time defaults to 59 seconds after midnight (00:00:59 +hours). +

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 any later date to the maximum +value. +
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. +
+

-portoffset +

Specifies one or more port offset numbers, each corresponding to a Tape +Coordinator to use in the operation. If there is more than one value, +the Backup System uses the first one when restoring the full dump of each +volume, the second one when restoring the level 1 incremental dump of each +volume, and so on. It uses the final value in the list when restoring +dumps at the corresponding depth in the dump hierarchy and all dumps at lower +levels. +

Provide this argument unless the default value of 0 (zero) is appropriate +for all dumps. If 0 is just one of the values in the list, provide it +explicitly in the appropriate order. +

-n +

Displays the list of tapes that contain the dumps required by the restore +operation, without actually performing the operation. +

If you did not include the -noautoquery flag when you issued +the butc command, or the device's +CFG_device_name configuration file includes the +instruction AUTOQUERY YES, then the Tape Coordinator prompts you to +place the tape in the device's drive. You have already done so, +but you must now press <Return> to indicate that the tape is +ready for labeling. +
If more than one tape is required, you must either include the +MOUNT instruction in the CFG_device_name file +and stock the corresponding stacker or jukebox with tapes, or remain at the +console to respond to the Tape Coordinator's prompts for subsequent +tapes. +
After the restore operation completes, review the Backup System's log +files to check for errors. Use the bos getlog command as +instructed in Displaying Server Process Log Files to read the /usr/afs/logs/BackupLog file, and a +text editor on the Tape Coordinator machine to read the +TE_device_name and TL_device_name +files in the local /usr/afs/backup directory. +

Using the backup diskrestore Command

+ + +

The backup diskrestore command is most appropriate when you need +to restore all of the volumes on an AFS server partition, perhaps because a +hardware failure has corrupted or destroyed all of the data. The +command performs a full restore of all of the read/write volumes for which the +VLDB lists the specified partition as the current site, using the dumps of +either the read/write or backup version of each volume depending on which type +was dumped more recently. (You can restore any backup or read-only +volumes that resided on the partition by using the vos backup and +vos release commands after the backup diskrestore +operation is complete.) +

By default, the Backup System restores the volumes to the site they +previously occupied. To move the partition contents to a different +site, use the -newserver and -newpartition arguments, +singly or in combination. +

By default, the Backup System overwrites the contents of existing volumes +with the restored data. To create a new volume to house the restored +data instead, use the -extension argument. The Backup System +creates the new volume at the site designated by the -newserver and +-newpartition arguments if they are used or the -server +and -partition arguments otherwise. It derives the volume +name by adding the extension to the read/write base name listed in the VLDB, +and creates a new VLDB entry. The command does not affect the existing +volume in any way. However, if a volume with the specified extension +also already exists, the command overwrites it. +

If a partition seems damaged, be sure not to run the vos +syncserv command before the backup diskrestore +command. As noted, the Backup System restores volumes according to VLDB +site definitions. The vos syncserv command sometimes removes +a volume's VLDB entry when the corruption on the partition is so severe +that the Volume Server cannot confirm the volume's presence. + + +

To restore a partition with the backup diskrestore command

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If the Tape Coordinator for the tape device that is to perform the +operation is not already running, open a connection to the appropriate Tape +Coordinator machine and issue the butc command, for which complete +instructions appear in To start a Tape Coordinator process. +
```
   % butc [<port offset>] [-noautoquery]
+
```
+
Repeat the command for each Tape Coordinator if you are using more than one +tape device. +
If using a tape device, insert the tape. +
Issue the backup command to enter interactive mode. +
```
   % backup
+
```
+
Issue the backup diskrestore command with the desired +arguments. +
```
   backup> diskrestore <machine to restore> <partition to restore>  \
+                       [-portoffset <TC port offset>⁺]  \
+                       [-newserver <destination machine>]  \
+                       [-newpartition <destination partition>]  \
+                       [-extension <new volume name extension>] [-n]
+
```
+
where +
+
di +
Is the shortest acceptable abbreviation of diskrestore. +
machine to restore +
Names the file server machine that the VLDB lists as the site of the +volumes that need to be restored. +
partition to restore +
Names the partition that the VLDB lists as the site of the volumes that +need to be restored. +
-portoffset +
Specifies one or more port offset numbers, each corresponding to a Tape +Coordinator to use in the operation. If there is more than one value, +the Backup System uses the first one when restoring the full dump of each +volume, the second one when restoring the level 1 incremental dump of each +volume, and so on. It uses the final value in the list when restoring +dumps at the corresponding depth in the dump hierarchy and all dumps at lower +levels. +
Provide this argument unless the default value of 0 (zero) is appropriate +for all dumps. If 0 is just one of the values in the list, provide it +explicitly in the appropriate order. +
-newserver +
Names an alternate file server machine to which to restore the +volumes. If you omit this argument, the volumes are restored to the +file server machine named by the -server argument. +
-newpartition +
Names an alternate partition to which to restore the data. If you +omit this argument, the volumes are restored to the partition named by the +-partition argument. +
-extension +
Creates a new volume for each volume being restored, to house the restored +data, appending the specified string to the volume's read/write base name +as listed in the VLDB. Any string other than +.readonly or .backup is acceptable, but +the combination of the base name and extension cannot exceed 22 characters in +length. To use a period to separate the extension from the name, +specify it as the first character of the string (as in .rst, +for example). +
-n +
Displays a list of the tapes necessary to perform the requested restore, +without actually performing the operation. +
+
If you did not include the -noautoquery flag when you issued +the butc command, or the device's +CFG_device_name configuration file includes the +instruction AUTOQUERY YES, then the Tape Coordinator prompts you to +place the tape in the device's drive. You have already done so, +but you must now press <Return> to indicate that the tape is +ready for labeling. +
If more than one tape is required, you must either include the +MOUNT instruction in the CFG_device_name file +and stock the corresponding stacker or jukebox with tapes, or remain at the +console to respond to the Tape Coordinator's prompts for subsequent +tapes. +
After the restore operation completes, review the Backup System's log +files to check for errors. Use the bos getlog command as +instructed in Displaying Server Process Log Files to read the /usr/afs/logs/BackupLog file, and a +text editor on the Tape Coordinator machine to read the +TE_device_name and TL_device_name +files in the local /usr/afs/backup directory. +

Using the backup volsetrestore Command

The backup volsetrestore command is most +appropriate when you need to perform a full restore of several read/write +volumes, placing each at a specified site. You specify the volumes to +restore either by naming a volume set with the -name argument or by +listing each volume's name and restoration site in a file named by the +-file argument, as described in the following sections. +

Because the backup volsetrestore command enables you to restore +a large number of volumes with a single command, the restore operation can +potentially take hours to complete. One way to reduce the time is to +run multiple instances of the command simultaneously. Either use the +-name argument to specify disjoint volume sets for each command, or +the -file argument to name files that list different +volumes. You must have several Tape Coordinators available to read the +required tapes. Depending on how the volumes to be restored were dumped +to tape, specifying disjoint volume sets can also reduce the number of tape +changes required. +

Restoring a Volume Set with the -name Argument

Use the -name argument to restore a group of +volumes defined in a volume set. The Backup System creates a list of +the volumes in the VLDB that match the server, partition, and volume name +criteria defined in the volume set's volume entries, and for which dumps +are available. The volumes do not have to exist on the server partition +as long as the VLDB still lists them (this can happen when, for instance, a +hardware problem destroys the contents of an entire disk). +

By default, the Backup System restores, as a read/write volume, each volume +that matches the volume set criteria to the site listed in the VLDB. If +a volume of the matching name exists at that site, its current contents are +overwritten. You can instead create a new volume to house the restored +data by including the -extension argument. The Backup System +creates the new volume at the existing volume's site, derives its name by +adding the extension to the existing volume's read/write base name, and +creates a new VLDB entry for it. The command does not affect the +existing volume in any way. However, if a volume with the specified +extension also already exists, the command overwrites it. To make the +contents of the new volume accessible, use the fs mkmount command +to mount it. You can then compare its contents to those of the existing +volume, to see which to retain permanently. +

It is not required that the volume set was previously used to back up +volumes (was used as the -volumeset option to the backup +dump command). It can be defined especially to match the volumes +that need to be restored with this command, and that is usually the better +choice. Indeed, a temporary volume set, created by including +the -temporary flag to the backup addvolset command, can +be especially useful in this context (instructions appear in Defining and Displaying Volume Sets and Volume Entries). A temporary volume set is not added to the Backup +Database and exists only during the current interactive backup session, which +is suitable if the volume set is needed only to complete the single restore +operation initialized by this command. +

The reason that a specially defined volume set is probably better is that +volume sets previously defined for use in dump operations usually match the +backup version of volumes, whereas for a restore operation it is best to +define volume entries that match the base (read/write) name. In this +case, the Backup System searches the Backup Database for the newest dump set +that includes a dump of either the read/write or the backup version of the +volume. If, in contrast, a volume entry explicitly matches the +volume's backup or read-only version, the Backup System uses dumps of +that volume version only, restoring them to a read/write volume by stripping +off the .backup or .readonly +extension. +

If there are VLDB entries that match the volume set criteria, but for which +there are no dumps recorded in the Backup Database, the Backup System cannot +restore them. It generates an error message on the standard error +stream for each one. +

Restoring Volumes Listed in a File with the -file Argument

Use the -file argument to specify the name and +site of each read/write volume to restore. Each volume's entry +must appear on its own (unbroken) line in the file, and comply with the +following format: +

   machine    partition   volume    [comments...]
+

where +

machine +: Names the file server machine to which to restore the volume. You +can move the volume as you restore it by naming a machine other than the +current site. +
partition +: Names the partition to which to restore the volume. You can move +the volume as you restore it by naming a partition other than the current +site. +
volume +: Names the volume to restore. Specify the base (read/write) name to +have the Backup System search the Backup Database for the newest dump set that +includes a dump of either the read/write or the backup version of the +volume. It restores the dumps of that version of the volume, starting +with the most recent full dump. If, in contrast, you include the +.backup or .readonly extension, the Backup +System restores dumps of that volume version only, but into a read/write +volume without the extension. The base name must match the name used in +Backup Database dump records rather than in the VLDB, if they differ, because +the Backup System does not consult the VLDB when you use the -file +argument. +
comments... +: Is any other text. The Backup System ignores any text on each line +that appears after the volume name, so you can use this field for helpful +notes. +

Do not use wildcards (for example, .*) in the +machine, partition, or volume fields. It is +acceptable for multiple lines in the file to name the same volume, but the +Backup System processes only the first of them. +

By default, the Backup System replaces the existing version of each volume +with the restored data, placing the volume at the site specified in the +machine and partition fields. You can instead create +a new volume to house the restored contents by including the +-extension argument. The Backup System creates a new volume +at the site named in the machine and partition fields, +derives its name by adding the specified extension to the read/write version +of the name in the volume field, and creates a new VLDB entry for +it. The command does not affect the existing volume in any way. +However, if a volume with the specified extension also already exists, the +command overwrites it. To make the contents of the new volume +accessible, use the fs mkmount command to mount it. You can +then compare its contents to those of the existing volume, to see which to +retain permanently. +

If the file includes entries for volumes that have no dumps recorded in the +Backup Database, the Backup System cannot restore them. It generates an +error message on the standard error stream for each one. +

One way to generate a file to use as input to the -file argument +is to issue the command with the -name and -n options +and direct the output to a file. The output includes a line like the +following for each volume (shown here on two lines only for legibility +reasons); the value comes from the source indicated in the following +list: +

   machine   partition   volume_dumped  # as   volume_restored;    \
+         tape_name   (tape_ID);   pos   position_number;   date
+

where +

machine +: Names the file server machine that currently houses the volume, as listed +in the VLDB. +
partition +: Names the partition that currently houses the volume, as listed in the +VLDB. +
volume_dumped +: Specifies the version (read/write or backup) of the volume that was +dumped, as listed in the Backup Database. +
volume_restored +: Specifies the name under which the Backup System restores the volume when +the -n flag is not included. If you include the +-extension argument with the -name and -n +options, then the extension appears on the name in this field (as in +user.pat.rst, for example). +
tape_name +: Names the tape containing the dump of the volume, from the Backup +Database. If the tape has a permanent name, it appears here; +otherwise, it is the AFS tape name. +
tape_ID +: The tape ID of the tape containing the dump of the volume, from the Backup +Database. +
position_number +: Specifies the dump's position on the tape (for example, 31 +indicates that 30 volume dumps precede the current one on the tape). If +the dump was written to a backup data file, this number is the ordinal of the +16 KB-offset at which the volume's data begins. +
date +: The date and time when the volume was dumped. +

To make the entries suitable for use with the -file argument, +edit them as indicated: +

The Backup System uses only the first three fields on each line of the +input file, and so ignores all the fields after the number sign +(#). You can remove them if it makes it easier for you to +read the file, but that is not necessary. +
The volume_dumped (third) field of each line in the output file +becomes the volume field in the input file. The Backup System +restores data to read/write volumes only, so remove the +.backup or .readonly extension if it +appears on the name in the volume_dumped field. +
The output file includes a line for every dump operation in which a +specific volume was included (the full dump and any incremental dumps), but +the Backup System only processes the first line in the input file that +mentions a specific volume. You can remove the repeated lines if it +makes the file easier for you to read. +
The machine and partition fields on an output line +designate the volume's current site. To move the volume to another +location as you restore it, change the values. +

+ + +

To restore a group of volumes with the backup volsetrestore command

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
If the Tape Coordinator for the tape device that is to perform the +operation is not already running, open a connection to the appropriate Tape +Coordinator machine and issue the butc command, for which complete +instructions appear in To start a Tape Coordinator process. +
```
   % butc [<port offset>] [-noautoquery]
+
```
+
Repeat the command for each Tape Coordinator if you are using more than one +tape device. +
If using a tape device, insert the tape. +
Issue the backup command to enter interactive mode. +
```
   % backup
+
```
+
(Optional) If appropriate, issue the (backup) +addvolset command to create a new volume set expressly for this restore +operation. Include the -temporary flag if you do not need to +add the volume set to the Backup Database. Then issue one or more +(backup) addvolentry commands to create volume entries that include +only the volumes to be restored. Complete instructions appear in Defining and Displaying Volume Sets and Volume Entries. +
```
   backup> addvolset <volume set name>  [-temporary]
+   
+   backup> addvolentry  -name <volume set name>  \
+                        -server <machine name>  \
+                        -partition <partition name>  \
+                        -volumes <volume name (regular expression)>
+
```
+
Issue the backup volsetrestore command with the desired +arguments. +
```
   backup> volsetrestore [-name <volume set name>]  \
+                 [-file <file name>]  \
+                 [-portoffset <TC port offset>⁺]  \
+                 [-extension <new volume name extension>] [-n] 
+
```
+
where +
+
-name +
Names a volume set to restore. The Backup System restores all of +the volumes listed in the VLDB that match the volume set's volume +entries, as described in Restoring a Volume Set with the -name Argument. Provide this argument or the -file +argument, but not both. +
-file +
Specifies the full pathname of a file that lists one or more volumes and +the site (file server machine and partition) to which to restore each. +The input file has the format described in Restoring Volumes Listed in a File with the -file Argument. Use either this argument or the -name +argument, but not both. +
-portoffset +
Specifies one or more port offset numbers, each corresponding to a Tape +Coordinator to use in the operation. If there is more than one value, +the Backup System uses the first one when restoring the full dump of each +volume, the second one when restoring the level 1 incremental dump of each +volume, and so on. It uses the final value in the list when restoring +dumps at the corresponding depth in the dump hierarchy and all dumps at lower +levels. +
Provide this argument unless the default value of 0 (zero) is appropriate +for all dumps. If 0 is just one of the values in the list, provide it +explicitly in the appropriate order. +
-extension +
Creates a new volume for each volume being restored, to house the restored +data, appending the specified string to the volume's read/write base name +as listed in the VLDB. Any string other than +.readonly or .backup is acceptable, but +the combination of the base name and extension cannot exceed 22 characters in +length. To use a period to separate the extension from the name, +specify it as the first character of the string (as in .rst, +for example). +
-n +
Displays a list of the volumes to be restored when the flag is not +included, without actually restoring them. The Output +section of this reference page details the format of the output. When +combined with the -name argument, its output is easily edited for +use as input to the -file argument on a subsequent backup +volsetrestore command. +
+
If you did not include the -noautoquery flag when you issued +the butc command, or the device's +CFG_device_name configuration file includes the +instruction AUTOQUERY YES, then the Tape Coordinator prompts you to +place the tape in the device's drive. You have already done so, +but you must now press <Return> to indicate that the tape is +ready for labeling. +
If more than one tape is required, you must either include the +MOUNT instruction in the CFG_device_name file +and stock the corresponding stacker or jukebox with tapes, or remain at the +console to respond to the Tape Coordinator's prompts for subsequent +tapes. +
After the restore operation completes, review the Backup System's log +files to check for errors. Use the bos getlog command as +instructed in Displaying Server Process Log Files to read the /usr/afs/logs/BackupLog file, and a +text editor on the Tape Coordinator machine to read the +TE_device_name and TL_device_name +files in the local /usr/afs/backup directory. +

+ +

Maintaining the Backup Database

The Backup Database stores all of the configuration and +tracking information that the Backup System uses when dumping and restoring +data. If a hardware failure or other problem on a database server +machine corrupts or damages the database, it is relatively easy to recreate +the configuration information (the dump hierarchy and lists of volume sets and +Tape Coordinator port offset numbers). However, restoring the dump +tracking information (dump records) is more complicated and +time-consuming. To protect yourself against loss of data, back up the +Backup Database itself to tape on a regular schedule. +

Another potential concern is that the Backup Database can grow large rather +quickly, because the Backup System keeps very detailed and cross-referenced +records of dump operations. Backup operations become less efficient if +the Backup Server has to navigate through a large number of obsolete records +to find the data it needs. To keep the database to a manageable size, +use the backup deletedump command to delete obsolete records, as +described in Removing Obsolete Records from the Backup Database. If you later find that you have removed records that +you still need, you can use the backup scantape command to read the +information from the dump and tape labels on the corresponding tapes back into +the database, as instructed in To scan the contents of a tape. + + + + + +

Backing Up and Restoring the Backup Database

Because of the importance of the information in the Backup +Database, it is best to back it up to tape or other permanent media on a +regular basis. As for the other AFS, administrative databases, the +recommended method is to use a utility designed to back up a machine's +local disk, such as the UNIX tar command. For instructions, +see Backing Up and Restoring the Administrative Databases. +

In the rare event that the Backup Database seems damaged or corrupted, you +can use the backup dbverify command to check its status. If +it is corrupted, use the backup savedb command to repair some types +of damage. Then use the backup restoredb to return the +corrected database to the local disks of the database server machines. +For instructions, see Checking for and Repairing Corruption in the Backup Database. +

Checking for and Repairing Corruption in the Backup Database

In rare cases, the Backup Database can become damaged or +corrupted, perhaps because of disk or other hardware errors. Use the +backup dbverify command to check the integrity of the +database. If it is corrupted, the most efficient way to repair it is to +use the backup savedb command to copy the database to tape. +The command automatically repairs several types of corruption, and you can +then use the backup restoredb command to transfer the repaired copy +of the database back to the local disks of the database server +machines. +

The backup savedb command also removes orphan blocks, +which 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. The backup dbverify command reports +the existence of orphan blocks if you include the -detail +flag. + + + +

To verify the integrity of the Backup Database

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the backup dbverify command to check the integrity of the +Backup Database. +
```
   % backup dbverify [-detail]
+
```
+
where +
+
db +
Is the shortest acceptable abbreviation of dbverify. +
-detail +
Reports the existence of orphan blocks and other information about the +database, as described on the backup dbverify reference page in the +IBM AFS Administration Reference. +
+
The output reports one of the following messages: +
- Database OK indicates that the Backup Database is +undamaged. +
- Database not OK indicates that the Backup Database is +damaged. To recover from the problem, use the instructions in To repair corruption in the Backup Database. +
+

+ + +

To repair corruption in the Backup Database

Log in as the local superuser root on each database server +machine in the cell. +
If the Tape Coordinator for the tape device that is to +perform the operation is not already running, open a connection to the +appropriate Tape Coordinator machine and issue the butc command, +for which complete instructions appear in To start a Tape Coordinator process. +
```
   % butc [<port offset>] [-noautoquery]
+
```
+
If writing to tape, place a tape in the appropriate device. +
Working on one of the machines, issue the backup command to +enter interactive mode. +
```
   #  backup -localauth
+
```
+
where -localauth constructs a server ticket from the local +/usr/afs/etc/KeyFile file. This flag enables you to issue a +privileged command while logged in as the local superuser root but +without AFS administrative tokens. +
Verify that no backup operations are actively running. If +necessary, issue the (backup) status command as described in To check the status of a Tape Coordinator process. Repeat for each Tape Coordinator port offset in +turn. +
```
   backup> status -portoffset <TC port offset>
+
```
+
Issue the (backup) savedb command to repair +corruption in the database as it is written to tape or a file. +
```
   backup> savedb [-portoffset <TC port offset>]
+
```
+
where +
+
sa +
Is the shortest acceptable abbreviation of savedb. +
-portoffset +
Specifies the port offset number of the Tape Coordinator handling the tape +or backup data file for this operation. You must provide this argument +unless the default value of 0 (zero) is appropriate. +
+
Exit interactive mode. +
```
   backup>  quit  
+
```
+
On each machine in turn, issue the bos shutdown command to shut +down the Backup Server process. Include the -localauth flag +because you are logged in as the local superuser root, but do not necessarily +have administrative tokens. For complete command syntax, see To stop processes temporarily. +
```
   # /usr/afs/bin/bos shutdown <machine name> buserver  -localauth  -wait
+
```
+
On each machine in turn, issue the following commands to remove the Backup +Database. +
```
   # cd /usr/afs/db
+   # rm bdb.DB0
+   # rm bdb.DBSYS1
+
```
+
On each machine in turn, starting with the machine with the lowest IP +address, issue the bos start command to restart the Backup Server +process, which creates a zero-length copy of the Backup Database as it +starts. For complete command syntax, see To start processes by changing their status flags to Run. +
```
   # /usr/afs/bin/bos start <machine name> buserver  -localauth
+
```
+
Working on one of the machines, issue the backup command to +enter interactive mode. +
```
   #  backup -localauth
+
```
+
where -localauth constructs a server ticket from the local +/usr/afs/etc/KeyFile file. +
Issue the (backup) addhost command to create an entry in the +new, empty database for the Tape Coordinator process handling the tape or file +from which you are reading the repaired copy of the database (presumably the +process you started in Step 2 and which performed the backup savedb operation +in Step 6). For complete syntax, see Step 8 in To configure a Tape Coordinator machine. +
```
   backup>  addhost <tape machine name> [<TC port offset>]
+
```
+ + +
Issue the (backup) restoredb command to copy the repaired +database to the database server machines. +
```
   backup> restoredb  [-portoffset <TC port offset>]
+
```
+
where +
+
res +
Is the shortest acceptable abbreviation of restoredb. +
-portoffset +
Specifies the port offset number of the Tape Coordinator handling the tape +or backup data file for this operation. You must provide this argument +unless the default value of 0 (zero) is appropriate. +
+
(Optional) Exit interactive mode if you do not plan to issue +any additional backup commands. +
```
   backup> quit
+
```
+
(Optional) If desired, enter Ctrl-d or another +interrupt signal to exit the root shell on each database server +machine. You can also issue the Ctrl-c signal on the Tape +Coordinator machine to stop the process. +

+ + +

Removing Obsolete Records from the Backup Database

Whenever you recycle or relabel a tape using the backup +dump or backup labeltape command, the Backup System +automatically removes all of the dump records for the dumps contained on the +tape and all other tapes in the dump set. However, obsolete records can +still accumulate in the Backup Database over time. For example, when +you discard a backup tape after using it the maximum number of times +recommended by the manufacturer, the records for dumps on it remain in the +database. Similarly, the Backup System does not automatically remove a +dump's record when the dump reaches its expiration date, but only if you +then recycle or relabel the tape that contains the dump. Finally, if a +backup operation halts in the middle, the records for any volumes successfully +written to tape before the halt remain in the database. +

A very large Backup Database can make backup operations less efficient +because the Backup Server has to navigate through a large number of records to +find the ones it needs. To remove obsolete records, use the backup +deletedump command. Either identify individual dumps by dump ID +number, or specify the removal of all dumps created during a certain time +period. Keep in mind that you cannot remove the record of an appended +dump except by removing the record of its initial dump, which removes the +records of all associated appended dumps. Removing records of a dump +makes it impossible to restore data from the corresponding tapes or from any +dump that refers to the deleted dump as its parent, directly or +indirectly. That is, restore operations must begin with the full dump +and continue with each incremental dump in order. If you have removed +the records for a specific dump, you cannot restore any data from later +incremental dumps. +

Another way to truncate the Backup Database is to include the +-archive argument to the backup savedb command. +After a copy of the database is written to tape or to a backup data file, the +Backup Server deletes the dump records for all dump operations with timestamps +prior to the date and time you specify. However, issuing the +backup deletedump command with only the -to argument is +equivalent in effect and is simpler because it does not require starting a +Tape Coordinator process as the backup savedb command does. +For further information on the -archive argument to the backup +savedb command, see the command's reference page in the IBM +AFS Administration Reference. +

If you later need to access deleted dump records, and the corresponding +tapes still exist, you can use the -dbadd argument to the +backup scantape command to scan their contents into the database, +as instructed in To scan the contents of a tape. + + +

To delete dump records from the Backup Database

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
(Optional) Issue the backup command to enter +interactive mode, if you want to delete multiple records or issue additional +commands. The interactive prompt appears in the following step. +
```
   % backup
+
```
+
(Optional) Issue the backup dumpinfo command to list +information from the Backup Database that can help you decide which records to +delete. For detailed instructions, see To display dump records. +
```
   backup> dumpinfo [<no. of dumps>]  [-id <dump id>]  [-verbose]
+
```
+

Issue the backup deletedump command to delete one or more dump +sets. +

   backup> deletedump [-dumpid <dumpid>⁺] [-from <date time>]  \
+                      [-to <date time>] 
+

where +

dele +

Is the shortest acceptable abbreviation of deletedump. +

-dumpid +

Specifies the dump ID of each initial dump to delete from the Backup +Database. The records for all associated appended dumps are also +deleted. Provide either this argument or the -to (and +optionally, -from) argument. +

-from +

Specifies the beginning of a range of dates; the record for any dump +created during the indicated period of time is deleted. +

To omit all records before the time indicated with the -to +argument, omit this argument. Otherwise provide a value in the +following format +

mm/dd/yyyy [hh:MM] +

where the month (mm), day (dd), and year (yyyy) +are required. You can omit the hour and minutes +(hh:MM) to indicate the default of midnight +(00:00 hours). If you provide them, use 24-hour format (for +example, the value 14:36 represents 2:36 +p.m.). +

You must provide the -to argument along with this one. +
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 +

Specifies the end of a range of dates; the record of any dump created +during the range is deleted from the Backup Database. +

To delete all records created after the date you specify with the +-from argument, specify the value NOW. To delete +every dump record in the Backup Database, provide the value NOW and +omit the -from argument. Otherwise, provide a date value in +the same format as described for the -from argument. Valid +values for the year (yyyy) range from 1970 to +2037; higher values are not valid because the latest possible +date in the standard UNIX representation is in early 2038. The command +interpreter automatically reduces any later date to the maximum value in +2038. +

If you omit the time portion (hh:MM), it defaults +to 59 seconds after midnight (00:00:59 hours). Similarly, +the backup command interpreter automatically adds 59 seconds to any +time value you provide. In both cases, adding 59 seconds compensates +for how the Backup Database and backup dumpinfo command represent +dump creation times in hours and minutes only. For example, the +Database records a creation timestamp of 20:55 for any dump +operation that begins between 20:55:00 and +20:55:59. Automatically adding 59 seconds to a time thus +includes the records for all dumps created during that minute. +

Provide either this argument, or the -dumpid argument. +This argument is required if the -from argument is provided. +
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. +
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd013.htm b/doc/html/AdminGuide/auagd013.htm new file mode 100644 index 0000000..2c08417 --- /dev/null +++ b/doc/html/AdminGuide/auagd013.htm @@ -0,0 +1,1873 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Monitoring and Auditing AFS Performance

+ + + + + + + + +

AFS comes with three main monitoring tools: +

The scout program, which monitors and gathers statistics on +File Server performance. +
The fstrace command suite, which traces Cache Manager +operations in detail. +
The afsmonitor program, which monitors and gathers statistics +on both the File Server and the Cache Manager. +

AFS also provides a tool for auditing AFS events on file server machines +running AIX. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + +
Initialize the scout program + scout +
Display information about a trace log + fstrace lslog +
Display information about an event set + fstrace lsset +
Change the size of a trace log + fstrace setlog +
Set the state of an event set + fstrace setset +
Dump contents of a trace log + fstrace dump +
Clear a trace log + fstrace clear +
Initialize the afsmonitor program + afsmonitor +
+

Using the scout Program

+ +

The scout program monitors the status of the File Server process +running on file server machines. It periodically collects statistics +from a specified set of File Server processes, displays them in a graphical +format, and alerts you if any of the statistics exceed a configurable +threshold. +

More specifically, the scout program includes the following +features. +

You can monitor, from a single location, the File Server process on any +number of server machines from the local and foreign cells. The number +is limited only by the size of the display window, which must be large enough +to display the statistics. +
You can set a threshold for many of the statistics. When the value +of a statistic exceeds the threshold, the scout program highlights +it (displays it in reverse video) to draw your attention to it. If the +value goes back under the threshold, the highlighting is deactivated. +You control the thresholds, so highlighting reflects what you consider to be a +noteworthy situation. See Highlighting Significant Statistics. +
The scout program alerts you to File Server process, machine, +and network outages by highlighting the name of each machine that does not +respond to its probe, enabling you to respond more quickly. +
You can set how often the scout program collects statistics +from the File Server processes. +

System Requirements

+ + + + + + + +

The scout program runs on any AFS client machine that has access +to the curses graphics package, which most UNIX distributions +include as a standard utility. It can run on both dumb terminals and +under windowing systems that emulate terminals, but the output looks best on +machines that support reverse video and cursor addressing. For best +results, set the TERM environment variable to the correct terminal type, or +one with characteristics similar to the actual ones. For machines +running AIX, the recommended TERM setting is vt100, assuming the +terminal is similar to that. For other operating systems, the wider +range of acceptable values includes xterm, xterms, +vt100, vt200, and wyse85. + +

No privilege is required to run the scout program, so any user +who can access the directory where its binary resides (the +/usr/afsws/bin directory in the conventional configuration) can use +it. The program's probes for collecting statistics do not impose a +significant burden on the File Server process, but you can restrict its use by +placing the binary file in a directory with a more restrictive access control +list (ACL). +

Multiple instances of the scout program can run on a single +client machine, each over its own dedicated connection (in its own +window). It must run in the foreground, so the window in which it runs +does not accept further input except for an interrupt signal. +

You can also run the scout program on several machines and view +its output on a single machine, by opening telnet connections to the other +machines from the central one and initializing the program in each remote +window. In this case, you can include the -host flag to the +scout command to make the name of each remote machine appear in the +banner line at the top of the window displaying its output. +See The Banner Line. +

Using the -basename argument to Specify a Domain Name

+ + +

As previously mentioned, the scout program can monitor the File +Server process on any number of file server machines. If all of the +machines belong to the same cell, then their hostnames probably all have the +same domain name suffix, such as abc.com in the ABC +Corporation cell. In this case, you can use the -basename +argument to the scout command, which has several advantages: +

You can omit the domain name suffix as you enter each file server +machine's name on the command line. The scout program +automatically appends the domain name to each machine's name, resulting +in a fully-qualified hostname. You can omit the domain name suffix even +when you don't include the -basename argument, but in that +case correct resolution of the name depends on the state of your cell's +naming service at the time of connection. +
The machine names are more likely to fit in the appropriate column of the +display without having to be truncated (for more on truncating names in the +display column, see The Statistics Display Region). +
The domain name appears in the banner line at the top of the display +window to indicate the name of the cell you are monitoring. +

The Layout of the scout Display

+ + +

The scout program can display statistics either in a dedicated +window or on a plain screen if a windowing environment is not +available. For best results, use a window or screen that can print in +reverse video and do cursor addressing. +

The scout program screen has three main regions: the +banner line, the statistics display region and the +probe/message line. This section describes their contents, +and graphic examples appear in Example Commands and Displays. +

The Banner Line

+ + +

By default, the string scout appears in the banner line at the +top of the window or screen, to indicate that the scout program is +running. You can display two additional types of information by include +the appropriate option on the command line: +

Include the -host flag to display the local machine's name +in the banner line. This is particularly useful when you are running +the scout program on several machines but displaying the results on +a single machine. +
For example, the following banner line appears when you run the +scout program on the machine +client1.abc.com and use the-host +flag: +
```
   [client1.abc.com] scout
+
```
+
Include the -basename argument to display the specified cell +domain name in the banner line. For further discussion, see Using the -basename argument to Specify a Domain Name. +
For example, if you specify a value of abc.com for the +-basename argument, the banner line reads: +
```
   scout for abc.com
+
```
+

The Statistics Display Region

+ + +

The statistics display region occupies most of the window and is divided +into six columns. The following list describes them as they appear from +left to right in the window. +

Conn + +

Displays the number of RPC connections open between the File Server +process and client machines. This number normally equals or exceeds the +number in the fourth Ws column. It can exceed the number in +that column because each user on the machine can have more than one connection +open at once, and one client machine can handle several users. +

Fetch + +

Displays the number of fetch-type RPCs (fetch data, fetch access list, and +fetch status) that the File Server process has received from client machines +since it started. It resets to zero when the File Server process +restarts. +

Store + +

Displays the number of store-type RPCs (store data, store access list, and +store status) that the File Server process has received from client machines +since it started. It resets to zero when the File Server process +restarts. +

Ws + + + +

Displays the number of client machines (workstations) that have +communicated with the File Server process within the last 15 minutes (such +machines are termed active). This number is likely to be +smaller than the number in the Conn) column because a single client +machine can have several connections open to one File Server process. +

[Unlabeled column] +

Displays the name of the file server machine on which the File Server +process is running. It is 12 characters wide. Longer names are +truncated and an asterisk (*) appears as the last character in the +name. If all machines have the same domain name suffix, you can use the +-basename argument to decrease the need for truncation; see Using the -basename argument to Specify a Domain Name. +

Disk attn + + + + +

Displays the number of kilobyte blocks available on up to 26 of the file +server machine's AFS server (/vicep) partitions. The +display for each partition has the following format: +

   partition_letter:free_blocks
+

For example, a:8949 indicates that partition +/vicepa has 8,949 KB free. If the window is not wide enough +for all partition entries to appear on a single line, the scout +program automatically stacks the partition entries into subcolumns within the +sixth column. +

The label on the Disk attn column indicates the threshold value +at which entries in the column become highlighted. By default, the +scout program highlights a partition that is over 95% full, in +which case the label is as follows: +

   Disk attn: > 95% used
+

For more on this threshold and its effect on highlighting, see Highlighting Significant Statistics. +

For all columns except the fifth (file server machine name), you can use +the -attention argument to set a threshold value above which the +scout program highlights the statistic. By default, only +values in the fifth and sixth columns ever become highlighted. For +instructions on using the -attention argument, see Highlighting Significant Statistics. +

The Probe Reporting Line

+ + +

The bottom line of the display indicates how many times the +scout program has probed the File Server processes for +statistics. The statistics gathered in the latest probe appear in the +statistics display region. By default, the scout program +probes the File Servers every 60 seconds, but you can use the +-frequency argument to specify a different probe frequency. +

Highlighting Significant Statistics

+ + + + +

To draw your attention to a statistic that currently exceed a threshold +value, the scout program displays it in reverse video (highlights +it). You can set the threshold value for most statistics, and so +determine which values are worthy of special attention and which are +normal. +

Highlighting Server Outages

+ + + + + +

The only column in which you cannot control highlighting is the fifth, +which identifies the file server machine for which statistics are displayed in +the other columns. The scout program uses highlighting in +this column to indicate that the File Server process on a machine fails to +respond to its probe, and automatically blanks out the other columns. +Failure to respond to the probe can indicate a File Server process, file +server machine, or network outage, so the highlighting draws your attention to +a situation that is probably interrupting service to users. +

When the File Server process once again responds to the probes, its name +appears normally and statistics reappear in the other columns. If all +machine names become highlighted at once, a possible network outage has +disrupted the connection between the file server machines and the client +machine running the scout program. +

Highlighting for Extreme Statistic Values

To set the threshold value for one or more of the five +statistics-displaying columns, use the -attention argument. +The threshold value applies to all File Server processes you are monitoring +(you cannot set different thresholds for different machines). For +details, see the syntax description in To start the scout program. +

It is not possible to change the threshold values for a running +scout program. Stop the current program and start a new +one. Also, the scout program does not retain threshold +values across restarts, so you must specify all thresholds every time you +start the program. +

Resizing the scout Display

+ + + +

Do not resize the display window while the scout program is +running. Increasing the size does no harm, but the scout +program does not necessarily adjust to the new dimensions. Decreasing +the display's width can disturb column alignment, making the display +harder to read. With any type of resizing, the scout program +does not adjust the display in any way until it displays the results of the +next probe. +

To resize the display effectively, stop the scout program, +resize the window and then restart the program. Even in this case, the +scout program's response depends on the accuracy of the +information it receives from the display environment. Testing during +development has shown that the display environment does not reliably provide +information about window resizing. If you use the X windowing system, +issuing the following sequence of commands before starting the +scout program (or placing them in the shell initialization file) +sometimes makes it adjust properly to resizing. +

   % set noglob
+   % eval '/usr/bin/X11/resize' 
+   % unset noglob
+

+ + + + + +

To start the scout program

Open a dedicated command shell. If necessary, adjust it to the +appropriate size. +
Issue the scout command to start the program. +
```
   % scout  [initcmd]  -server <FileServer name(s) to monitor>⁺  \
+            [-basename <base server name>]  \
+            [-frequency <poll frequency, in seconds>] [-host]  \
+            [-attention <specify attention (highlighting) level>⁺]  \
+            [-debug <turn debugging output on to the named file>]
+
```
+
where +
+
initcmd +
Is an optional string that accommodates the command's use of the AFS +command parser. It can be omitted and ignored. +
-server +
Identifies each File Server process to monitor, by naming the file server +machine it is running on. Provide fully-qualified hostnames unless the +-basename argument is used. In that case, specify only the +initial part of each machine name, omitting the domain name suffix common to +all the machine names. +
-basename +
Specifies the domain name suffix common to all of the file server machines +named by the -server argument. For discussion of this +argument's effects, see Using the -basename argument to Specify a Domain Name. +
Do not include the period that separates the domain suffix from the initial +part of the machine name, but do include any periods that occur within the +suffix itself. (For example, in the ABC Corporation cell, the proper +value is abc.com, not +.abc.com.) +
-frequency +
Sets the frequency, in seconds, of the scout program's +probes to File Server processes. Specify an integer greater than 0 +(zero). The default is 60 seconds. +
-host +
Displays the name of the machine that is running the scout +program in the display window's banner line. By default, no +machine name is displayed. +
-attention +
Defines the threshold value at which to highlight one or more +statistics. You can provide the pairs of statistic and threshold in any +order, separating each pair and the parts of each pair with one or more +spaces. The following list defines the syntax for each +statistic. + + + +
+
conn connections +
Highlights the value in the Conn (first) column when the number +of connections that the File Server has open to client machines exceeds the +connections value. The highlighting deactivates when the value +goes back below the threshold. There is no default threshold. +
fetch fetch_RPCs +
Highlights the value in the Fetch (second) column when the +number of fetch RPCs that clients have made to the File Server process exceeds +the fetch_RPCs value. The highlighting deactivates only when +the File Server process restarts, at which time the value returns to +zero. There is no default threshold. +
store store_RPCs +
Highlights the value in the Store (third) column when the +number of store RPCs that clients have made to the File Server process exceeds +the store_RPCs value. The highlighting deactivates only when +the File Server process restarts, at which time the value returns to +zero. There is no default threshold. +
ws active_clients +
Highlights the value in the Ws (fourth) column when the number +of active client machines (those that have contacted the File Server in the +last 15 minutes) exceeds the active_clients value. The +highlighting deactivates when the value goes back below the threshold. +There is no default threshold. +
disk percent_full % or disk min_blocks +
Highlights the value for a partition in the Disk attn (sixth) +column when either the amount of disk space used exceeds the percentage +indicated by thepercent_full value, or the number of free KB blocks +is less than the min_blocks value. The highlighting +deactivates when the value goes back below the percent_full threshold +or above the min_blocks threshold. +
The value you specify appears in the header of the sixth column following +the string Disk attn. The default threshold is 95% +full. +
Acceptable values for percent_full are the integers from the range +0 (zero) to 99, and you must include the percent sign to +distinguish this statistic from a min_blocks value.. +
+
The following example sets the threshold for the Conn column to +100, for the Ws column to 50, and for the Disk attn +column to 75%. There is no threshold for the Fetch and +Store columns. +
-attention conn 100 ws 50 disk 75% +
The following example has the same affect as the previous one except that +it sets the threshold for the Disk attn column to 5000 free KB +blocks: +
-attention disk 5000 ws 50 conn 100 +
-debug +
Enables debugging output and directs it into the specified file. +Partial pathnames are interpreted relative to the current working +directory. By default, no debugging output is produced. +
+

To stop the scout program

+ +

Enter Ctrl-c in the display window. This is the proper +interrupt signal even if the general interrupt signal in your environment is +different. +

Example Commands and Displays

+ + +

This section presents examples of the scout program, combining +different arguments and illustrating the screen displays that result. +

In the first example, an administrator in the ABC Corporation issues the +scout command without providing any optional arguments or +flags. She includes the -server argument because she is +providing multiple machine names. She chooses to specify on the initial +part of each machine's name even though she has not used the +-basename argument, relying on the cell's name service to +obtain the fully-qualified name that the scout program requires for +establishing a connection. +

   % scout -server fs1 fs2 
+

Figure 2 depicts the resulting display. Notice first that the +machine names in the fifth (unlabeled) column appear in the format the +administrator used on the command line. Now consider the second line in +the display region, where the machine name fs2 appears in the fifth +column. The Conn and Ws columns together show +that machine fs2 has 144 RPC connections open to 44 client +machines, demonstrating that multiple connections per client machine are +possible. The Fetch column shows that client machines have +made 2,734,278 fetch RPCs to machine fs2 since the File Server +process last started and the Store column shows that they have made +34,066 store RPCs. +

Six partition entries appear in the Disk attn column, marked +a through f (for /vicepa through +/vicepf). They appear on three lines in two subcolumns +because of the width of the window; if the window is wider, there are +more subcolumns. Four of the partition entries (a, +c, d, and e) appear in reverse video to +indicate that they are more than 95% full (the threshold value that appears in +the Disk attn header). +

Figure 2. First example scout display
+

+

+
+

In the second example, the administrator uses more of the scout +program's optional arguments. +

She provides the machine names in the same form as in Example 1, but this +time she also uses the -basename argument to specify their domain +name suffix, abc.com. This implies that the +scout program does not need the name service to expand the names to +fully-qualified hostnames, but the name service still converts the hostnames +to IP addresses. +
She uses the -host flag to display in the banner line the name +of the client machine where the scout program is running. +
She uses the -frequency argument to changes the probing +frequency from its default of once per minute to once every five +seconds. +
She uses the -attention argument to changes the highlighting +threshold for partitions to a 5000 KB minimum rather than the default of 95% +full. +

   % scout -server fs1 fs2 -basename abc.com -host -frequency 5 -attention disk 5000 
+

The use of optional arguments results in several differences between Figure 3 and Figure 2. First, because the -host +flag is included, the banner line displays the name of the machine running the +scout process as [client52] along with the basename +abc.com specified with the -basename +argument. +

Another difference is that two rather than four of machine +fs2's partitions appear in reverse video, even though their +values are almost the same as in Figure 2. This is because the administrator changed the +highlight threshold to a 5000 block minimum, as also reflected in the +Disk attn column's header. And while machine +fs2's partitions /vicepa and /vicepd are +still 95% full, they have more than 5000 free blocks left; partitions +/vicepc and /vicepe are highlighted because they have +fewer than 5000 blocks free. +

Note also the result of changing the probe frequency, reflected in the +probe reporting line at the bottom left corner of the display. Both +this example and the previous one represent a time lapse of one minute after +the administrator issues the scout command. In this example, +however, the scout program has probed the File Server processes 12 +times as opposed to once +

Figure 3. Second example scout display
+

+

+
+

In Figure 4, an administrator in the State University cell monitors +three of that cell's file server machines. He uses the +-basename argument to specify the stateu.edu +domain name. +

   % scout -server server2 server3 server4 -basename stateu.edu 
+

Figure 4. Third example scout display
+

+

+
+

Figure 5 illustrates three of the scout program's +features. First, you can monitor file server machines from different +cells in a single display: fs1.abc.com, +server3.stateu.edu, and +sv7.def.com. Because the machines belong to +different cells, it is not possible to provide the -basename +argument. +

Second, it illustrates how the display must truncate machine names that do +not fit in the fifth column, using an asterisk at the end of the name to show +that it is shortened. +

Third, it illustrates what happens when the scout process cannot +reach a File Server process, in this case the one on the machine +sv7.def.com: it highlights the machine name and +blanks out the values in the other columns. +

Figure 5. Fourth example scout display
+

+

+
+

Using the fstrace Command Suite

This section describes the fstrace commands that +system administrators employ to trace Cache Manager activity for debugging +purposes. It assumes the reader is familiar with the Cache Manager +concepts described in Administering Client Machines and the Cache Manager. +

The fstrace command suite monitors the internal activity of the +Cache Manager and enables you to record, or trace, its operations in +detail. The operations, which are termed events, comprise +the cm event set. Examples of cm +events are fetching files and looking up information for a listing of files +and subdirectories using the UNIX ls command. +

Following are the fstrace commands and their respective +functions: +

The fstrace apropos command provides a short description of +commands. +
The fstrace clear command clears the trace log. +
The fstrace dump command dumps the contents of the trace +log. +
The fstrace help command provides a description and syntax for +commands. +
The fstrace lslog command lists information about the trace +log. +
The fstrace lsset command lists information about the event +set. +
The fstrace setlog command changes the size of the trace +log. +
The fstrace setset command sets the state of the event +set. +

About the fstrace Command Suite

The fstrace command suite replaces and greatly +expands the functionality formerly provided by the fs debug +command. Its intended use is to aid in diagnosis of specific Cache +Manager problems, such as client machine hangs, cache consistency problems, +clock synchronization errors, and failures to access a volume or AFS +file. Therefore, it is best not to keep fstrace logging +enabled at all times, unlike the logging for AFS server processes. +

Most of the messages in the trace log correspond to low-level Cache Manager +operations. It is likely that only personnel familiar with the AFS +source code can interpret them. If you have an AFS source license, you +can attempt to interpret the trace yourself, or work with the AFS Product +Support group to resolve the underlying problems. If you do not have an +AFS source license, it is probably more efficient to contact the AFS Product +Support group immediately in case of problems. They can instruct you to +activate fstrace tracing if appropriate. +

The log can grow in size very quickly; this can use valuable disk +space if you are writing to a file in the local file space. +Additionally, if the size of the log becomes too large, it can become +difficult to parse the results for pertinent information. + + +

When AFS tracing is enabled, each time a cm event occurs, a +message is written to the trace log, cmfx. To diagnose a +problem, read the output of the trace log and analyze the operations executed +by the Cache Manager. The default size of the trace log is 60 KB, but +you can increase or decrease it. + + +

To use the fstrace command suite, you must first enable tracing +and reserve, or allocate, space for the trace log with the fstrace +setset command. With this command, you can set the cm +event set to one of three states to enable or disable tracing for the event +set and to allocate or deallocate space for the trace log in the kernel: + + + +

active +: Enables tracing for the event set and allocates space for the trace +log. +
inactive +: Temporarily disables tracing for the event set; however, the event +set continues to allocate space occupied by the log to which it sends +data. +
dormant +: Disables tracing for the event set; furthermore, the event set +releases the space occupied by the log to which it sends data. When the +cm event set that sends data to the cmfx trace log is in +this state, the space allocated for that log is freed or deallocated. +

+ + + +

Both event sets and trace logs can be designated as persistent, +which prevents accidental resetting of an event set's state or clearing +of a trace log. The designation is made as the kernel is compiled and +cannot be changed. +

If an event set such as cm is persistent, you can change its +state only by including the -set argument to the fstrace +setset command. (That is, you cannot change its state along with +the state of all other event sets by issuing the fstrace setset +command with no arguments.) Similarly, if a trace log such as +cmfx is persistent, you can clear it only by including either the +-set or -log argument to the fstrace clear +command (you cannot clear it along with all other trace logs by issuing the +fstrace clear command with no arguments.) +

When a problem occurs, set the cm event set to active using the +fstrace setset command. When tracing is enabled on a busy +AFS client, the volume of events being recorded is significant; +therefore, when you are diagnosing problems, restrict AFS activity as much as +possible to minimize the amount of extraneous tracing in the log. +Because tracing can have a negative impact on system performance, leave +cm tracing in the dormant state when you are not diagnosing +problems. +

If a problem is reproducible, clear the cmfx trace log with the +fstrace clear command and reproduce the problem. If the +problem is not easily reproduced, keep the state of the event set active until +the problem recurs. +

To view the contents of the trace log and analyze the cm events, +use the fstrace dump command to copy the content lines of the trace +log to standard output (stdout) or to a file. +
Note: If a particular command or process is causing problems, determine its process +id (PID). Search the output of the fstrace dump command for +the PID to find only those lines associated with the problem. +
+

Requirements for Using the fstrace Command Suite

+ + +

Except for the fstrace help and fstrace apropos +commands, which require no privilege, issuing the fstrace commands +requires that the issuer be logged in as the local superuser root +on the local client machine. Before issuing an fstrace +command, verify that you have the necessary privilege. +

The Cache Manager catalog must be in place so that logging can +occur. The fstrace command suite uses the standard UNIX +catalog utilities. The default location is +/usr/vice/etc/C/afszcm.cat. It can be placed in +another directory by placing the file elsewhere and using the proper NLSPATH +and LANG environment variables. +

Using fstrace Commands Effectively

To use fstrace commands most effectively, configure them as +indicated: +

Store the fstrace binary in a local disk directory. +
When you dump the fstrace log to a file, direct it to one on +the local disk. +
The trace can grow large in just a few minutes. Before attempting +to dump the log to a local file, verify that you have enough room. Be +particularly careful if you are using disk quotas on partitions in the local +file system. +
Attempt to limit Cache Manager activity on the AFS client machine other +than the problem operation. This reduces the amount of extraneous data +in the trace. +
Activate the fstrace log for the shortest possibly period of +time. If possible activate the trace immediately before performing the +problem operation, deactivate it as soon as the operation completes, and dump +the trace log to a file immediately. +
If possible, obtain UNIX process ID (PID) of the command or program that +initiates the problematic operation. This enables the person analyzing +the trace log to search it for messages associated with the PID. +

Activating the Trace Log

To start Cache Manager tracing on an AFS client machine, you +must first configure +

The cmfx kernel trace log using the fstrace setlog +command +
The cm event set using the fstrace setset command +

The fstrace setlog command sets the size of the cmfx +kernel trace log in kilobytes. The trace log occupies 60 kilobytes of +kernel by default. If the trace log already exists, it is cleared when +this command is issued and a new log of the given size is created. +Otherwise, a new log of the desired size is created. +

The fstrace setset command sets the state of the cm +kernel event set. The state of the cm event set determines +whether information on the events in that event set is logged. +

After establishing kernel tracing on the AFS client machine, you can check +the state of the event set and the size of the kernel buffer allocated for the +trace log. To display information about the state of the cm +event set, issue the fstrace lsset command. To display +information about the cmfx trace log, use the fstrace +lslog command. See the instructions in Displaying the State of a Trace Log or Event Set. + + + + +

To configure the trace log

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+

Issue the fstrace setlog command to set the size of the +cmfx kernel trace log. +

   # fstrace setlog  [-log <log_name>⁺]  -buffersize <1-kilobyte_units>
+

The following example sets the size of the cmfx trace log to 80 +KB. +

   # fstrace setlog cmfx 80 
+

+ + + + +

To set the event set

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+

Issue the fstrace setset command to set the state of event +sets. +

   % fstrace setset [-set <set_name>⁺] [-active] [-inactive]  \
+                    [-dormant] 
+

The following example activates the cm event set. +

   # fstrace setset cm -active
+

Displaying the State of a Trace Log or Event Set

An event set must be in the active state to be +included in the trace log. To display an event set's state, use +the fstrace lsset command. To set its state, issue the +fstrace setset command as described in To set the event set. +

To display size and allocation information for the trace log, issue the +fstrace lslogcommand with the -long argument. + + + + +

To display the state of an event set

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fstrace lsset command to display the available event +set and its state. +
```
   # fstrace lsset  [-set <set_name>⁺]
+
```
+

The following example displays the event set and its state on the local +machine. +

   # fstrace lsset cm
+   Available sets:
+   cm active
+

The output from this command lists the event set and its states. The +three event states for the cm event set are: +

active +: Tracing is enabled. +
inactive +: Tracing is disabled, but space is still allocated for the corresponding +trace log (cmfx). +
dormant +: Tracing is disabled, and space is no longer allocated for the +corresponding trace log (cmfx).Disables tracing for the +event set. +

+ + + + +

To display the log size

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fstrace lslog command to display information about +the kernel trace log. +
```
   # fstrace lslog  [-set <set_name>⁺]  [-log <log_name>]  [-long] 
+
```
+

The following example uses the -long flag to display additional +information about the cmfx trace log. +

   # fstrace lslog cmfx -long
+   Available logs:
+   cmfx : 60 kbytes (allocated)
+

The output from this command lists information on the trace log. +When issued without the -long flag, the fstrace lslog +command lists only the name of the log. When issued with the +-long flag, the fstrace lslog command lists the log, the +size of the log in kilobytes, and the allocation state of the log. +

There are two allocation states for the kernel trace log: +

allocated +: Space is reserved for the log in the kernel. This indicates that +the event set that writes to this log is either active (tracing is +enabled for the event set) or inactive (tracing is temporarily +disabled for the event set); however, the event set continues to reserve +space occupied by the log to which it sends data. +
unallocated +: Space is not reserved for the log in the kernel. This indicates +that the event set that writes to this log is dormant (tracing is +disabled for the event set); furthermore, the event set releases the +space occupied by the log to which it sends data. +

Dumping and Clearing the Trace Log

After the Cache Manager operation you want to trace is +complete, use the fstrace dump command to dump the trace log to the +standard output stream or to the file named by the -file +argument. Or, to dump the trace log continuously, use the +-follow argument (combine it with the -file argument if +desired). To halt continuous dumping, press an interrupt signal such as +<Ctrl-c>. +

To clear a trace log when you no longer need the data in it, issue the +fstrace clear command. (The fstrace setlog +command also clears an existing trace log automatically when you use it to +change the log's size.) + + + + + +

To dump the contents of a trace log

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+

Issue the fstrace dump command to dump trace logs. +

   # fstrace dump [-set <set_name>⁺]  [-follow <log_name>]  \
+                  [-file <output_filename>]  \
+                  [-sleep <seconds_between_reads>]
+

At the beginning of the output of each dump is a header specifying the date +and time at which the dump began. The number of logs being dumped is +also displayed if the -follow argument is not specified. The +header appears as follows: +

   AFS Trace Dump --
+   Date: date time
+   Found n logs.
+

where date is the starting date of the trace log dump, +time is the starting time of the trace log dump, and n +specifies the number of logs found by the fstrace dump +command. +

The following is an example of trace log dump header: +

   AFS Trace Dump --
+   Date: Fri Apr 16 10:44:38 1999
+   Found 1 logs.
+

The contents of the log follow the header and are comprised of messages +written to the log from an active event set. The messages written to +the log contain the following three components: +

The timestamp associated with the message (number of seconds from an +arbitrary start point) +
The process ID or thread ID associated with the message +
The message itself +

A trace log message is formatted as follows: +

   time timestamp, pid pid:event message
+

where timestamp is the number of seconds from an arbitrary start +point, pid is the process ID number of the Cache Manager event, and +event message is the Cache Manager event which corresponds with a +function in the AFS source code. +

The following is an example of a dumped trace log message: +

   time 749.641274, pid 3002:Returning code 2 from 19
+

For the messages in the trace log to be most readable, the Cache Manager +catalog file needs to be installed on the local disk of the client +machine; the conventional location is +/usr/vice/etc/C/afszcm.cat. Log messages that begin +with the string raw op, like the following, indicate that the +catalog is not installed. +

   raw op 232c, time 511.916288, pid 0
+   p0:Fri Apr 16 10:36:31 1999
+

Every 1024 seconds, a current time message is written to each log. +This message has the following format: +

   time timestamp, pid pid: Current time: unix_time
+

where timestamp is the number of seconds from an arbitrary start +point, pid is the process ID number, and unix_time is the +standard time format since January 1, 1970. +

The current time message can be used to determine the actual time +associated with each log message. Determine the actual time as +follows: +

Locate the log message whose actual time you want to determine. +
Search backward through the dump record until you come to a current time +message. +
If the current time message's timestamp is smaller than +the log message's timestamp, subtract the former from the +latter. If the current time message's timestamp is +larger than the log message's timestamp, add 1024 to the +latter and subtract the former from the result. +
Add the resulting number to the current time message's +unix_time to determine the log message's actual time. +

Because log data is stored in a finite, circular buffer, some of the data +can be overwritten before being read. If this happens, the following +message appears at the appropriate place in the dump: +

   Log wrapped; data missing.
+

Note:

If this message appears in the middle of a dump, which can happen under a +heavy work load, it indicates that not all of the log data is being written to +the log or some data is being overwritten. Increasing the size of the +log with the fstrace setlog command can alleviate this +problem. +

+ + + + + +

To clear the contents of a trace log

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fstrace clear command to clear logs by log name or by +event set. +
```
   # fstrace clear  [-set <set_name>⁺]  [-log <log_name>⁺]
+
```
+

The following example clears the cmfx log used by the +cm event set on the local machine. +

   # fstrace clear cm
+

The following example also clears the cmfx log on the local +machine. +

   # fstrace clear cmfx
+

+ +

Examples of fstrace Commands

This section contains an extensive example of the use of the +fstrace command suite, which is useful for gathering a detailed +trace of Cache Manager activity when you are working with AFS Product Support +to diagnose a problem. The Product Support representative can guide you +in choosing appropriate parameter settings for the trace. +

Before starting the kernel trace log, try to isolate the Cache Manager on +the AFS client machine that is experiencing the problem accessing the +file. If necessary, instruct users to move to another machine so as to +minimize the Cache Manager activity on this machine. To minimize the +amount of unrelated AFS activity recorded in the trace log, place both the +fstrace binary and the dump file must reside on the local disk, not +in AFS. You must be logged in as the local superuser root to +issue fstrace commands. +

Before starting a kernel trace, issue the fstrace lsset command +to check the state of the cm event set. +

   # fstrace lsset cm
+

If tracing has not been enabled previously or if tracing has been turned +off on the client machine, the following output is displayed: +

   Available sets:
+   cm inactive
+

If tracing has been turned off and kernel memory is not allocated for the +trace log on the client machine, the following output is displayed: +

   Available sets:
+   cm inactive (dormant)
+

If the current state of the cm event set is inactive +or inactive (dormant), turn on kernel tracing by issuing the +fstrace setset command with the -active flag. +

   # fstrace setset cm -active
+

If tracing is enabled currently on the client machine, the following output +is displayed: +

   Available sets:
+   cm active
+

If tracing is enabled currently, you do not need to use the fstrace +setset command. Do issue the fstrace clear command to +clear the contents of any existing trace log, removing prior traces that are +not related to the current problem. +

   # fstrace clear cm
+

After checking on the state of the event set, issue the fstrace +lslog command with the -long flag to check the current state +and size of the kernel trace log . +

   # fstrace lslog cmfx -long
+

If tracing has not been enabled previously or the cm event set +was set to active or inactive previously, output similar +to the following is displayed: +

   Available logs:
+   cmfx : 60 kbytes (allocated)
+

The fstrace tracing utility allocates 60 kilobytes of memory to +the trace log by default. You can increase or decrease the amount of +memory allocated to the kernel trace log by setting it with the fstrace +setlog command. The number specified with the +-buffersize argument represents the number of kilobytes allocated +to the kernel trace log. If you increase the size of the kernel trace +log to 100 kilobytes, issue the following command. +

   # fstrace setlog cmfx 100
+

After ensuring that the kernel trace log is configured for your needs, you +can set up a file into which you can dump the kernel trace log. For +example, create a dump file with the name +cmfx.dump.file.1 using the following +fstrace dump command. Issue the command as a continuous +process by adding the -follow and -sleep +arguments. Setting the -sleep argument to 10 +dumps output from the kernel trace log to the file every 10 seconds. +

   # fstrace dump -follow cmfx -file cmfx.dump.file.1 -sleep 10
+   AFS Trace Dump -
+      Date: Fri Apr 16 10:54:57 1999
+   Found 1 logs.
+   time 32.965783, pid 0: Fri Apr 16 10:45:52 1999
+   time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20 
+   time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns
+   0x0) 
+   time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024
+   (volume 0)
+   time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024
+   (volume 0)
+       .                         .
+       .                         .
+       .                         .
+   time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs fid (756
+   4fb7e:588d240.2ff978a8.6) 
+   time 71.440569, pid 33658: Returning code 2 from 19 
+   time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns
+   0x2) 
+   time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x
+   0) 
+   AFS Trace Dump - Completed
+

Using the afsmonitor Program

+ +

The afsmonitor program enables you to monitor the status and +performance of specified File Server and Cache Manager processes by gathering +statistical information. Among its other uses, the +afsmonitor program can be used to fine-tune Cache Manager +configuration and load balance File Servers. +

The afsmonitor program enables you to perform the following +tasks. +

Monitor any number of File Server and Cache Manager processes on any +number of machines (in both local and foreign cells) from a single +location. +
Set threshold values for any monitored statistic. When the value of +a statistic exceeds the threshold, the afsmonitor program +highlights it to draw your attention. You can set threshold levels that +apply to every machine or only some. +
Invoke programs or scripts automatically when a statistic exceeds its +threshold. +

Requirements for running the afsmonitor program

+ +

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. +

+ +No privilege is required to run the afsmonitor program. By +convention, it is installed in the /usr/afsws/bin directory, and +anyone who can access the directory can monitor File Servers and Cache +Managers. The probes through which the afsmonitor program +collects statistics do not constitute a significant burden on the File Server +or Cache Manager unless hundreds of people are running the program. If +you wish to restrict its use, place the binary file in a directory available +only to authorized users. +

The afsmonitor Output Screens

+ +

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 following graphic is an example System Overview +screen. The afsmonitor program is monitoring six File +Servers and seven Cache Managers. The File Server process on host +fs1.abc.com and the Cache Manager on host +cli33.abc.com are each marked [ 1] to +indicate that one threshold value is exceeded. The [PF] +marker on host fs6.abc.com indicates that its File +Server process did not respond to the last probe. +

Figure 6. The afsmonitor System Overview Screen
+

+

+
+

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. +

For a list of the available File Server statistics, see Appendix C, The afsmonitor Program Statistics. +

The following graphic depicts the File Servers screen that +follows the System Overview Screen example previously discussed; however, +one additional server probe has been completed. In this example, the +File Server process on fs1 has exceeded the configured threshold +for the number of performance calls received (the numPerfCalls +statistic), and that field appears in reverse video. Host +fs6 did not respond to Probe 10, so dashes appear in all +fields. +

Figure 7. The afsmonitor File Servers Screen
+

+

+
+

Both the File Servers and Cache Managers screen (discussed in the following +section) can display hundreds of columns of data and are therefore designed to +scroll left and right. In the preceding graphic, the screen displays +the leftmost screen and the screen title block shows that column 1 of 235 is +displayed. The appearance of the >>> symbol in the upper +right hand corner of the screen and the right command in the +command block indicate that additional data is available by scrolling +right. (For information on the available statistics, see Appendix C, The afsmonitor Program Statistics.) +

If the right command is executed, the screen looks something +like the following example. Note that the horizontal scroll symbols now +point both to the left (<<<) and to the right +(>>>) and both the left and right commands +appear, indicating that additional data is available by scrolling both left +and right. +

Figure 8. The afsmonitor File Servers Screen Shifted One Page to the Right
+

+

+
+

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. +

For a list of the available Cache Manager statistics, see Appendix C, The afsmonitor Program Statistics. +

The following graphic depicts a Cache Managers screen that follows the +System Overview Screen previously discussed. In the example, the Cache +Manager process on host cli33 has exceeded the configured threshold +for the number of cells it can contact (the numCellsContacted +statistic), so that field appears in reverse video. +

Figure 9. The afsmonitor Cache Managers Screen
+
+

+
+

Configuring the afsmonitor Program

+ + +

To customize the afsmonitor program, create an ASCII-format +configuration file and use the -config argument to name it. +You can specify the following in the configuration file: +

The File Servers, Cache Managers, or both to monitor. +
The statistics to display. By default, the display includes 271 +statistics for File Servers and 570 statistics for Cache Managers. For +information on the available statistics, see Appendix C, The afsmonitor Program Statistics. +
The threshold values to set for statistics and a script or program to +execute if a threshold is exceeded. By default, no threshold values are +defined and no scripts or programs are executed. +

The following list describes the instructions that can appear in the +configuration file: +

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] [arg₁] . . . +[arg_n] +

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 arg₁ through +arg_n 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 parameters fs, cm, field_name, +threshold_val, and arg₁ through +arg_n 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 equals or 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 Appendix C, The afsmonitor Program Statistics.) +

The following example illustrates a possible configuration file: +

   thresh cm dlocalAccesses  1000000
+   thresh cm dremoteAccesses  500000 handleDRemote
+   thresh fs rx_maxRtt_Usec     1000
+   cm client5
+   cm client33
+   cm client14
+   thresh cm dlocalAccesses  2000000
+   thresh cm vcacheMisses      10000
+   cm client2
+   fs fs3
+   fs fs9
+   fs fs5
+   fs fs10
+   show cm numCellsContacted
+   show cm dlocalAccesses
+   show cm dremoteAccesses
+   show cm vcacheMisses
+   show cm Auth_Stats_group
+

Since the first three thresh instructions appear before any +fs or cm instructions, they set global threshold +values: +

All Cache Manager process in this file use 1000000 as the +threshold for the dlocalAccesses statistic (except for the machine +client2 which uses an overriding value of +2000000.) +
All Cache Manager processes in this file use 500000 as the +threshold value for the dremoteAccesses statistic; if that +value is exceeded, the script handleDRemote is invoked. +
All File Server processes in this file use 1000 as the +threshold value for the rx_maxRtt_Usec statistic. +

The four cm instructions monitor the Cache Manager on the +machines client5, client33, client14, and +client2. The first three use all of the global threshold +values. +

The Cache Manager on client2 uses the global threshold value for +the dremoteAccesses statistic, but a different one for the +dlocalAccesses statistic. Furthermore, client22 +is the only Cache Manager that uses the threshold set for the +vcacheMisses statistic. +

The fs instructions monitor the File Server on the machines +fs3, fs9, fs5, and fs10. +They all use the global threshold for therx_maxRtt_Usec +statistic. +

Because there are no show fs instructions, the File Servers +screen displays all File Server statistics. The Cache Managers screen +displays only the statistics named in show cm instructions, +ordering them from left to right. The Auth_Stats_group +includes several statistics, all of which are displayed (curr_PAGs, +curr_Records, curr_AuthRecords, +curr_UnauthRecords, curr_MaxRecordsInPAG, +curr_LongestChain, PAGCreations, +TicketUpdates, HWM_PAGS, HWM_Records, +HWM_MaxRecordsInPAG, and HWM_LongestChain). +

Writing afsmonitor Statistics to a File

+ +

All of the statistical information collected and displayed by the +afsmonitor program can be preserved by writing it to an output +file. You can create an output file by using the -output +argument when you startup the afsmonitor process. You can +use the output file to track process performance over long periods of time and +to apply post-processing techniques to further analyze system trends. +

The afsmonitor program output file is a simple ASCII file that +records the information reported by the File Server and Cache Manager +screens. The output file has the following format: +

   time   host_name CM|FS   list_of_measured_values
+

and specifies the time at which the +list_of_measured_values were gathered from the Cache Manager +(CM) or File Server (FS) process housed on +host_name. On those occasion where probes fail, the value +-1 is reported instead of the +list_of_measured_values. +

This file format provides several advantages: +

It can be viewed using a standard editor. If you intend to view +this file frequently, use the -detailed flag with the +-output argument. It formats the output file in a way that +is easier to read. +
It can be passed through filters to extract desired information using the +standard set of UNIX tools. +
It is suitable for long term storage of the afsmonitor program +output. +

+ + +

To start the afsmonitor Program

Open a separate command shell window or use a dedicated terminal for each +instance of the afsmonitor program. This window or terminal +must be devoted to the exclusive use of the afsmonitor process +because the command cannot be run in the background. +
Initialize the afsmonitor program. The message +afsmonitor Collecting Statistics..., followed by +the appearance of the System Overview screen, confirms a successful +start. +
```
   % 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>⁺]
+   afsmonitor Collecting Statistics...
+
```
+
where +
+
initcmd +
Is an optional string that accommodates the command's use of the AFS +command parser. It can be omitted and ignored. +
-config +
Specifies the pathname of an afsmonitor configuration file, +which lists the machines and statistics to monitor. Partial pathnames +are interpreted relative to the current working directory. Provide +either this argument or one or both of the -fshosts and +-cmhosts arguments. You must use a configuration file to set +thresholds or customize the screen display. For instructions on +creating the configuration file, see Configuring the afsmonitor Program. +
-frequency +
Specifies how often to probe the File Server and Cache Manager processes, +as a number of seconds. Acceptable values range from 1 and +86400; the default value is 60. This +frequency applies to both File Server and Cache Manager probes; however, +File Server and Cache Manager probes are initiated and processed independent +of each other. The actual interval between probes to a host is the +probe frequency plus the time needed by all hosts to respond to the +probe. +
-output +
Specifies the name of an output file to which to write all of the +statistical data. By default, no output file is created. For +information on this file, see Writing afsmonitor Statistics to a File. +
-detailed +
Formats the output file named by the -output argument to be +more easily readable. The -output argument must be provided +along with this flag. +
-fshosts +
Identifies each File Server process to monitor by specifying the host it +is running on. You can identify a host using either its complete +Internet-style host name or an abbreviation acceptable to the cell's +naming service. Combine this argument with the -cmhosts if +you wish, but not the -config argument. +
-cmhosts +
Identifies each Cache Manager process to monitor by specifying the host it +is running on. You can identify a host using either its complete +Internet-style host name or an abbreviation acceptable to the cell's +naming service. Combine this argument with the -fshosts if +you wish, but not the -config argument. +
+

To stop the afsmonitor program

+ +

To exit an afsmonitor program session, Enter the +<Ctrl-c> interrupt signal or an uppercase Q. +

The xstat Data Collection Facility

+ + + + + + + + + + + +

The afsmonitor program uses the xstat data collection +facility to gather and calculate the data that it (the afsmonitor +program) then uses to perform its function. You can also use the +xstat facility to create your own data display programs. If +you do, keep the following in mind. The File Server considers any +program calling its RPC routines to be a Cache Manager; therefore, any +program calling the File Server interface directly must export the Cache +Manager's callback interface. The calling program must be capable +of emulating the necessary callback state, and it must respond to periodic +keep-alive messages from the File Server. In addition, a calling +program must be able to gather the collected data. +

The xstat facility consists of two C language libraries +available to user-level applications: +

/usr/afsws/lib/afs/libxstat_fs.a exports calls that +gather information from one or more running File Server processes. +
/usr/afsws/lib/afs/libxstat_cm.a exports calls that +collect information from one or more running Cache Managers. +

The libraries allow the caller to register +

A set of File Servers or Cache Managers to be examined. +
The frequency with which the File Servers or Cache Managers are to be +probed for data. +
A user-specified routine to be called each time data is collected. +

The libraries handle all of the lightweight processes, callback +interactions, and timing issues associated with the data collection. +The user needs only to process the data as it arrives. +

The libxstat Libraries

+ + +

The libxstat_fs.a and libxstat_cm.a +libraries handle the callback requirements and other complications associated +with the collection of data from File Servers and Cache Managers. The +user provides only the means of accumulating the desired data. Each +xstat library implements three routines: +

Initialization (xstat_fs_Init and xstat_cm_Init) +arranges the periodic collection and handling of data. +
Immediate probe (xstat_fs_ForceProbeNow and +xstat_cm_ForceProbeNow) forces the immediate collection of data, +after which collection returns to its normal probe schedule. +
Cleanup (xstat_fs_Cleanup and xstat_cm_Cleanup) +terminates all connections and removes all traces of the data collection from +memory. +

+ + + + + +The File Server and Cache Manager each define data collections that clients +can fetch. A data collection is simply a related set of numbers that +can be collected as a unit. For example, the File Server and Cache +Manager each define profiling and performance data collections. The +profiling collections maintain counts of the number of times internal +functions are called within servers, allowing bottleneck analysis to be +performed. The performance collections record, among other things, +internal disk I/O statistics for a File Server and cache effectiveness figures +for a Cache Manager, allowing for performance analysis. +

+ + + +For a copy of the detailed specification which provides much additional usage +information about the xstat facility, its libraries, and the +routines in the libraries, contact AFS Product Support. +

Example xstat Commands

+ + + + + +

AFS comes with two low-level, example commands: +xstat_fs_test and xstat_cm_test. The commands +allow you to experiment with the xstat facility. They gather +information and display the available data collections for a File Server or +Cache Manager. They are intended merely to provide examples of the +types of data that can be collected via xstat; they are not +intended for use in the actual collection of data. + + + + +

To use the example xstat_fs_test command

Issue the example xstat_fs_test command to test the routines in +the libxstat_fs.a library and display the data collections +associated with the File Server process. The command executes in the +foreground. +
```
   % xstat_fs_test [initcmd]  \
+                   -fsname <File Server name(s) to monitor>⁺  \
+                   -collID <Collection(s) to fetch>⁺  [-onceonly]  \
+                   [-frequency <poll frequency, in seconds>]  \
+                   [-period <data collection time, in minutes>] [-debug] 
+
```
+
where +
+
xstat_fs_test +
Must be typed in full. +
initcmd +
Is an optional string that accommodates the command's use of the AFS +command parser. It can be omitted and ignored. +
-fsname +
Is the Internet host name of each file server machine on which to monitor +the File Server process. +
-collID +
Specifies each data collection to return. The indicated data +collection defines the type and amount of data the command is to gather about +the File Server. Data is returned in the form of a predefined data +structure (refer to the specification documents referenced previously for more +information about the data structures). +
There are two acceptable values: +
- 1 reports various internal performance statistics related to +the File Server (for example, vnode cache entries and Rx protocol +activity). +
- 2 reports all of the internal performance statistics provided +by the 1 setting, plus some additional, detailed performance +figures about the File Server (for example, minimum, maximum, and cumulative +statistics regarding File Server RPCs, how long they take to complete, and how +many succeed). +
+
-onceonly +
Directs the command to gather statistics just one time. Omit this +option to have the command continue to probe the File Server for statistics +every 30 seconds. If you omit this option, you can use the +<Ctrl-c> interrupt signal to halt the command at any +time. +
-frequency +
Sets the frequency in seconds at which the program initiates probes to the +File Server. If you omit this argument, the default is 30 +seconds. +
-period +
Sets how long the utility runs before exiting, as a number of +minutes. If you omit this argument, the default is 10 minutes. +
-debug +
Displays additional information as the command runs. +
+

+ + + + +

To use the example xstat_cm_test command

Issue the example xstat_cm_test command to test the routines in +the libxstat_cm.a library and display the data collections +associated with the Cache Manager. The command executes in the +foreground. +
```
   % xstat_cm_test [initcmd]  \
+                   -cmname <Cache Manager name(s) to monitor>⁺  \
+                   -collID <Collection(s) to fetch>⁺ \
+                   [-onceonly] [-frequency <poll frequency, in seconds>]  \
+                   [-period <data collection time, in minutes>] [-debug] 
+
```
+
where +
+
xstat_cm_test +
Must be typed in full. +
initcmd +
Is an optional string that accommodates the command's use of the AFS +command parser. It can be omitted and ignored. +
-cmname +
Is the host name of each client machine on which to monitor the Cache +Manager. +
-collID +
Specifies each data collection to return. The indicated data +collection defines the type and amount of data the command is to gather about +the Cache Manager. Data is returned in the form of a predefined data +structure (refer to the specification documents referenced previously for more +information about the data structures). +
There are two acceptable values: +
- 0 provides profiling information about the numbers of times +different internal Cache Manager routines were called since the Cache manager +was started. +
- 1 reports various internal performance statistics related to +the Cache manager (for example, statistics about how effectively the cache is +being used and the quantity of intracell and intercell data access). +
- 2 reports all of the internal performance statistics provided +by the 1 setting, plus some additional, detailed performance +figures about the Cache Manager (for example, statistics about the number of +RPCs sent by the Cache Manager and how long they take to complete; and +statistics regarding things such as authentication, access, and PAG +information associated with data access). +
+
-onceonly +
Directs the command to gather statistics just one time. Omit this +option to have the command continue to probe the Cache Manager for statistics +every 30 seconds. If you omit this option, you can use the +<Ctrl-c> interrupt signal to halt the command at any +time. +
-frequency +
Sets the frequency in seconds at which the program initiates probes to the +Cache Manager. If you omit this argument, the default is 30 +seconds. +
-period +
Sets how long the utility runs before exiting, as a number of +minutes. If you omit this argument, the default is 10 minutes. +
-debug +
Displays additional information as the command runs. +
+

Auditing AFS Events on AIX File Servers

+ + + + +

You can audit AFS events on AIX File Servers using an AFS mechanism that +transfers audit information from AFS to the AIX auditing system. The +following general classes of AFS events can be audited. For a complete +list of specific AFS audit events, see Appendix D, AIX Audit Events. +

Authentication and Identification Events +
Security Events +
Privilege Required Events +
Object Creation and Deletion Events +
Attribute Modification Events +
Process Control Events +

Note:

This section assumes familiarity with the AIX auditing system. For +more information, see the AIX System Management Guide for the +version of AIX you are using. +

Configuring AFS Auditing on AIX File Servers

The directory /usr/afs/local/audit contains three files that +contain the information needed to configure AIX File Servers to audit AFS +events: +

The events.sample file contains information on auditable +AFS events. The contents of this file are integrated into the +corresponding AIX events file (/etc/security/audit/events). +
The config.sample file defines the six classes of AFS +audit events and the events that make up each class. It also defines +the classes of AFS audit events to audit for the File Server, which runs as +the local superuser root. The contents of this file must be +integrated into the corresponding AIX config file +(/etc/security/audit/config). +
The objects.sample file contains a list of information +about audited files. You must only audit files in the local file +space. The contents of this file must be integrated into the +corresponding AIX objects file +(/etc/security/audit/objects). +

Once you have properly configured these files to include the AFS-relevant +information, use the AIX auditing system to start up and shut down the +auditing. +

To enable AFS auditing

Create the following string in the file /usr/afs/local/Audit on +each File Server on which you plan to audit AFS events: +
```
   AFS_AUDIT_AllEvents
+
```
+
Issue the bos restart command (with the -all flag) +to stop and restart all server processes on each File Server. For +instructions on using this command, see Stopping and Immediately Restarting Processes. +

To disable AFS auditing

Remove the contents of the file /usr/afs/local/Audit on each +File Server for which you are no longer interested in auditing AFS +events. +
Issue the bos restart command (with the -all flag) +to stop and restart all server processes on each File Server. For +instructions on using this command, see Stopping and Immediately Restarting Processes. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd014.htm b/doc/html/AdminGuide/auagd014.htm new file mode 100644 index 0000000..13aba01 --- /dev/null +++ b/doc/html/AdminGuide/auagd014.htm @@ -0,0 +1,831 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Managing Server Encryption Keys

This chapter explains how to maintain your cell's +server encryption keys, which are vital for secure communications in +AFS. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + +
Add a new server encryption key + bos addkey and kas setpassword +
Inspect key checksums in the Authentication Database + kas examine +
Inspect key checksums in the KeyFile + bos listkeys +
Remove an old server encryption key + bos removekey +
+

About Server Encryption Keys

+ + +

An encryption key is a string of octal numbers used to encrypt +and decrypt packets of information. In AFS, a server encryption +key is the key used to protect information being transferred between AFS +server processes and between them and their clients. A server +encryption key is essentially a password for a server process and like a user +password is stored in the Authentication Database. +

Maintaining your cell's server encryption keys properly is the most +basic way to protect the information in your AFS filespace from access by +unauthorized users. +

Keys and Mutual Authentication: A Review

+ + + + + + +

Server encryption keys play a central role in the mutual authentication +between client and server processes in AFS. For a more detailed +description of mutual authentication, see A More Detailed Look at Mutual Authentication. +

When a client wants to contact an AFS server, it first contacts the +Ticket Granting Service (TGS) module of the Authentication +Server. After verifying the client's identity (based indirectly on +the password of the human user whom the client represents), the TGS gives the +client a server ticket. This ticket is encrypted with the +server's encryption key. (The TGS also invents a second encryption +key, called the session key, to be used only for a single episode +of communication between server and client. The server ticket and +session key, together with other pieces of information, are collectively +referred to as a token.) +

The client cannot read the server ticket or token because it does not know +the server encryption key. However, the client sends it to the AFS +server along with service requests, because the ticket proves to the AFS +server processes that it has already authenticated with the TGS. AFS +servers trust the TGS to grant tickets only to valid clients. The fact +that the client possesses a ticket encrypted with the server's encryption +key proves to the server that the client is valid. On the other hand, +the client assumes that only a genuine AFS server knows the server encryption +key needed to decrypt the ticket. The server's ability to decrypt +the ticket and understand its contents proves to the client that the server is +legitimate. +

Maintaining AFS Server Encryption Keys

As you maintain your cell's server encryption keys, keep the +following in mind. +

Change the key frequently to enhance your cell's security. +Changing the key at least once a month is strongly recommended. + +
The AFS server encryption key currently in use is stored in two +places. When you add a new key, you must make changes in both places +and make them in the correct order, as instructed in Adding Server Encryption Keys. Failure to follow the instructions can seriously +impair cell functioning, as clients and servers become unable to +communicate. The two storage sites for the current server encryption +key are the following: +
1. The file /usr/afs/etc/KeyFile on the local disk of every file +server machine. The file can list more than one key, each with an +associated numerical identifier, the key version number or +kvno. A client token records the key version number of the +key used to seal it, and the server process retrieves the appropriate key from +this file when the client presents the token. + + + + + +
2. The afs entry in the Authentication Database. The +current server encryption key is in the entry's password field, just like +an individual user's scrambled password. The Authentication +Server's Ticket Granting Service (TGS) uses this key to encrypt the +tokens it gives to clients. There is only a single key in the entry, +because the TGS never needs to read existing tokens, but only to generate new +ones by using the current key. + + + +
+
For instructions on creating the initial afs entry and +KeyFile files as you install your cell's first server machine, +see the IBM AFS Quick Beginnings. +
At any specific time, the tokens that the Authentication Server's +Ticket Granting Service gives to clients are sealed with only one of the +server encryption keys, namely the one stored in the afs entry in +the Authentication Database. +
When you add a new server encryption key, you cannot immediately remove +the former key from the /usr/afs/etc/KeyFile file on the local disk +of every AFS server machine. Any time that you add a new key, it is +likely that some clients still have valid, unexpired tokens sealed with the +previous key. The more frequently you change the server encryption key, +the more such tickets there are likely to be. To be able to grant +service appropriately to clients with such tokens, an AFS server process must +still be able to access the server encryption key used to seal it. +
You can safely delete an old server encryption key only when it is certain +that no clients have tokens sealed with that key. In general, wait a +period of time at least as long as the maximum token lifetime in your +cell. By default, the maximum token lifetime for users is 25 hours +(except for users whose Authentication Database entries were created by using +the 3.0 version of AFS, for whom the default is 100 hours). You +can use the -lifetime argument to the kas setfields +command to change this default. +
Instructions for removing obsolete keys appear in Removing Server Encryption Keys. +
You create a new AFS server encryption key in much the same way regular +users change their passwords, by providing a character string that is +converted into an encryption key automatically. See Adding Server Encryption Keys. + +
In addition to using server encryption keys when communicating with +clients, the server processes use them to protect communications with other +server processes. Therefore, all server machines in your cell must have +the same version of the KeyFile file. The easiest way to +maintain consistency (if you run the United States edition of AFS) is to use +the Update Server to distribute the contents of the system control +machine's /usr/afs/etc directory to all of the other server +machines. There are two implications: +
- You must run the upserver process on the system control machine +and an upclientetc process on all other server machines that +references the system control machine. The IBM AFS Quick +Beginnings explains how to install both processes. For +instructions on verifying that the Update Server processes are running, see Displaying Process Status and Information from the BosConfig File. + +
- Change the KeyFile file only on the system control machine +(except in the types of emergencies discussed in Handling Server Encryption Key Emergencies). Any changes you make on other server machines are +overwritten the next time the upclientetc process retrieves the +contents of the system control machine's /usr/afs/etc +directory. By default, this happens every five minutes. + +
+
If you run the international edition of AFS, do not use the Update Server +to distribute the contents of the /usr/afs/etc directory, +particularly the KeyFile file. The data in the file is too +sensitive for transfer in unencrypted form, and because of United States +government exports regulations the international edition of AFS does not +include the necessary encryption routines in a form that the Update Server can +use. You must instead modify the file on each server machine +individually, taking care to enter the same key on every server +machine. +
Never edit the KeyFile directly with a text editor. +Instead, always use the appropriate bos commands as instructed in Adding Server Encryption Keys and Removing Server Encryption Keys. +

Displaying Server Encryption Keys

To display the server encryption keys in the +/usr/afs/etc/KeyFile file on any file server machine, use the +bos listkeys command. Use the kas examine command +to display the key in the Authentication Database's afs +entry. +

By default the commands do not display the actual string of octal digits +that constitute a key, but rather a checksum, a decimal number +derived by encrypting a constant with the key. This prevents +unauthorized users from easily accessing the actual key, which they can then +use to falsify or eavesdrop on protected communications. + + +The bos listkeys and kas examine commands generate the +same checksum for a given key, so displaying checksums rather than actual keys +is generally sufficient. If you suspect that the keys differ in a way +that the checksums are not revealing, then you are probably experiencing +authentication problems throughout your cell. The easiest solution is +to create a new server encryption key following the instructions in Adding Server Encryption Keys or Handling Server Encryption Key Emergencies. Another common reason to issue the +bos listkeys command is to display the key version numbers +currently in use, in preparation for choosing the next one; here, the +checksum is sufficient because the key itself is irrelevant. +

If it is important to display the actual octal digits, include the +-showkey argument to both the bos listkeys and kas +examine commands. + + + + + + +

To display the KeyFile file

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos listkeys command to display the contents of one +machine's /usr/afs/etc/KeyFile file. +
```
   % bos listkeys <machine name> [-showkey]
+
```
+
where +
+
listk +
Is the shortest acceptable abbreviation of listkeys. +
machine name +
Names a file server machine. In the normal case, it is acceptable +to name any machine, because correct cell functioning requires that the +KeyFile file be the same on all of them. +
-showkey +
Displays the octal digits that constitute each key. +
+

In the following example, the output displays a checksum for each server +encryption key rather than the actual octal digits. The penultimate +line indicates when an administrator last changed the file, and the final line +confirms that the output is complete. +

   % bos listkeys fs1.abc.com
+   key 0 has cksum 972037177
+   key 1 has cksum 2825165022
+   Keys last changed on Wed Jan 13 11:20:29 1999. 
+   All done.
+

+ + + + + + +

To display the afs key from the Authentication Database

Issue the kas examine command to display the afs +entry in the Authentication Database. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas examine afs [-showkey]  \
+                 -admin  <admin principal to use for authentication>  
+   Administrator's (admin_user) password: admin_password 
+
```
+
where +
+
e +
Is the shortest acceptable abbreviation of examine. +
afs +
Designates the afs entry. +
-showkey +
Displays the octal digits that constitute the key. +
-admin +
Names an administrative account with the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
+

In the following example, the admin user displays the +afs entry without using the -showkey flag. The +second line shows the key version number in parentheses and the key's +checksum. The line that begins with the string last mod +reports the date on which the indicated administrator changed the key. +There is no necessary relationship between this date and the date reported by +the bos listkeys command, because the latter date changes for any +type of change to the KeyFile file, not just a key addition. +For a description of the other lines in the output from the kas +examine command, see its reference page in the IBM AFS +Administration Reference. +

   % kas examine afs  -admin admin
+   Administrator's (admin) password: admin_password 
+   User data for afs
+    key (1) cksum is 2825165022, last cpw: no date
+    password will never expire.
+    An unlimited number of unsuccessful authentications is permitted.
+    entry expires on never. Max ticket lifetime 100.00 hours.
+    last mod on Wed Jan 13 11:21:36 1999 by admin
+    permit password reuse
+

Adding Server Encryption Keys

+ + + + + + + + + +

As noted, AFS records server encryption keys in two separate places: +

In the file /usr/afs/etc/KeyFile on the local disk of each +server machine, for use by the AFS server processes running on the machine +
In the afs entry in the Authentication Database, for use by the +Ticket Granting Service (TGS) when creating tokens +

To ensure that server processes and the TGS share the same AFS server +encryption key, execute all the steps in this section without +interruption. +

The following instructions include a step in which you restart the database +server processes (the Authentication, Backup, Protection, and Volume Location +Server processes) on all database server machines. As a database server +process starts, it reads in the server encryption key that has the highest key +version number in the KeyFile file and uses it to protect the +messages that it sends for synchronizing the database and maintaining +quorum. It uses the same key throughout its lifetime, which can be for +an extended period, even if you remove the key from the KeyFile +file. However, if one of the peer database server processes restarts +and the others do not, quorum and database synchronization break down because +the processes are no longer using the same key: the restarted process is +using the key that currently has the highest key version number, and the other +processes are still using the key they read in when they originally +started. To avoid this problem, it is safest to restart all of the +database server processes when adding a new key. +

After adding a new key, you can remove obsolete keys from the +KeyFile file to prevent it from becoming cluttered. However, +you must take care not to remove keys that client or server processes are +still using. For discussion and instructions, see Removing Server Encryption Keys. +

To add a new server encryption key

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos listkeys command to display the key +version numbers that are already in use, as a first step in choosing the key +version number for the new key. +
```
   % bos listkeys <machine name>
+
```
+
where +
+
listk +
Is the shortest acceptable abbreviation of listkeys. +
machine name +
Names any file server machine. +
+
Choose a key version number for the new key, based on the +output from Step 2 and the following requirements: +
- A key version number must be an integer between 0 (zero) and 255 to comply +with Kerberos standards. It is simplest if you keep your key version +numbers in sequence by choosing a key version number one greater than the +largest existing one. +
- Do not reuse a key version number currently found in the +KeyFile file, particularly if it is also the one in the +Authentication Database afs entry. Client processes possibly +still have tickets sealed with the key that originally had that key version +number, but the server processes start using the new key marked with that key +version number. Because the keys do not match, the server processes +refuse requests from clients who hold legitimate tokens. +
+ + +
Issue the bos addkey command to create a new AFS +server encryption key in the KeyFile file. +
If you run the United States edition of AFS and use the Update Server to +distribute the contents of the system control machine's +/usr/afs/etc directory, substitute the system control machine for +the machine name argument. (If you have forgotten which +machine is the system control machine, see To locate the system control machine.) +
If you run the international edition of AFS or do not use the Update +Server, repeat the bos addkey command, substituting each server +machine in your cell for the machine name argument in turn. +
To avoid visible echoing of the string that corresponds to the new key, +omit the -key argument from the command line; instead enter +the string at the prompts that appear when you omit it, as shown in the +following syntax specification. +
```
   % bos addkey  -server <machine name> -kvno <key version number>
+   input key: afs_password
+   Retype input key: afs_password
+
```
+
where +
+
addk +
Is the shortest acceptable abbreviation of addkey. +
-server +
Names the cell's system control machine if you are using the Update +Server, or each server machine in turn if you are not. +
-kvno +
Specifies the new key's key version number as an integer from the +range 0 (zero) through 255. +
Remember the number. You need to use it again in Step 6. If you are using the international edition of AFS, +be sure to type the same number each time you issue this command. +
afs_password +
Is a character string similar to a user password, of any length from one +to about 1,000 characters. To improve security, include nonalphabetic +characters and make the string as long as is practical (you need to type it +only in this step and in Step 6). If you are using the international edition of AFS, +be sure to type the same string each time you issue this command. +
Do not enter an octal string directly. The BOS Server scrambles the +character string into an octal string appropriate for use as an encryption key +before recording it in the KeyFile file. +
+
If you are using the Update Server, wait for a few minutes while the +Update Server distributes the new KeyFile file to all server +machines. The maximum necessary waiting period is the largest value +provided for the -t argument to the upclientetc +process's initialization command used on any of the server machines; +the default time is five minutes. +
To be certain that all machines have the same KeyFile file, +issue the bos listkeys command for every file server machine and +verify that the checksum for the new key is the same on all machines. +
```
   % bos listkeys <machine name>
+
```
+
If you are not using the Update Server, try to complete Step 4 within five minutes. + + +
Issue the kas setpassword command to enter the same +key in the afs entry in the Authentication Database. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas setpassword -name afs -kvno <kvno>  \
+                     -admin  <admin principal to use for authentication>  
+   Administrator's (admin_user) password: admin_password 
+   new_password: afs_password
+   Verifying, please re-enter new_password: afs_password
+
```
+
where +
+
sp +
Is an acceptable alias for setpassword (setp is the +shortest acceptable abbreviation). +
-name afs +
Creates the new key in the afs entry. +
-kvno +
Specifies the same key version number as in Step 4. +
-admin +
Names an administrative account with the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
afs_password +
Is the same character string you entered in Step 4. +
+
(Optional.) If you want to verify that the keys you just +created in the KeyFile file and the Authentication Database +afs entry are identical and have the same key version number, +follow the instructions in Displaying Server Encryption Keys. +
Issue the bos restart command to restart the database server +processes on all database server machines. This forces them to start +using the key in the KeyFile file that currently has the highest +key version number. +
Repeat this command in quick succession for each database server machine, +starting with the machine that has the lowest IP address. +
```
   % bos restart  <machine name> buserver kaserver ptserver vlserver
+
```
+
where +
+
res +
Is the shortest acceptable abbreviation of restart. +
machine name +
Names each database server machine in turn. +
buserver kaserver ptserver vlserver +
Designates the Backup Server, Authentication Server, Protection Server, +and Volume Location (VL) Server, respectively. +
+

Removing Server Encryption Keys

+ + + +

You can periodically remove old keys from the +/usr/afs/etc/KeyFile file to keep it to a reasonable size. +To avoid disturbing cell functioning, do not remove an old key until all +tokens sealed with the key and held by users or client processes have +expired. After adding a new key, wait to remove old keys at least as +long as the longest token lifetime you use in your cell. For +Authentication Database user entries created under AFS version 3.1 or +higher, the default token lifetime is 25 hours; for entries created under +AFS version 3.0, it is 100 hours. +

There is no command for removing the key from the afs entry in +the Authentication Database, because the key field in that entry must never be +empty. Use the kas setpassword command to replace the +afs key, but only as part of the complete procedure detailed in To add a new server encryption key. +

Never remove from the KeyFile file the key that is currently in +the afs entry in the Authentication Database. AFS server +processes become unable to decrypt the tickets that clients present to +them. +

To remove a key from the KeyFile file

Verify that you are authenticated as a user listed in the +/usr/afs/etc/UserList file. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos listkeys command to display the key version +number of each key you want to remove. The output also reveals whether +it has been at least 25 hours since a new key was placed in the +KeyFile file. For complete instructions for the bos +listkeys command, see To display the KeyFile file. +
```
   % bos listkeys <machine name>
+
```
+
Issue the kas examine command to verify that the key currently +in the Authentication Database's afs entry does not have the +same key version number as any of the keys you are removing from the +KeyFile file. For detailed instructions for the kas +examine command, see To display the afs key from the Authentication Database. +
```
   % kas examine afs  -admin <admin principal to use for authentication>  
+   Administrator's (admin_user) password: admin_password 
+
```
+ + +
Issue the bos removekey command to remove one or more server +encryption keys from the KeyFile file. +
If you run the United States edition of AFS and use the Update Server to +distribute the contents of the system control machine's +/usr/afs/etc directory, substitute the system control machine for +the machine name argument. (If you have forgotten which +machine is the system control machine, see To locate the system control machine.) +
If you run the international edition of AFS or do not use the Update +Server, repeat the bos removekey command, substituting each server +machine in your cell for the machine name argument in turn. +
```
   % bos removekey <machine name> <key version number>
+
```
+
where +
+
removek +
Is the shortest acceptable abbreviation of removekey. +
machine name +
Names the cell's system control machine if you are using the Update +Server, or each server machine in turn if you are not. +
key version number +
Specifies the key version number of each key to remove. +
+

Handling Server Encryption Key Emergencies

+ + + + + +

In rare circumstances, the AFS server processes can become unable to +decrypt the server tickets that clients or peer server processes are +presenting. Activity in your cell can come to a halt, because the +server processes believe that the tickets are forged or expired, and refuse to +execute any actions. This can happen on one machine or several; +the effect is more serious when more machines are involved. +

One common cause of server encryption key problems is that the +client's ticket is encrypted with a key that the server process does not +know. Usually this means that the /usr/afs/etc/KeyFile on +the server machine does not include the key in the afs +Authentication Database entry, which the Authentication Server's Ticket +Granting Service (TGS) module is using to encrypt server tickets. +

Another possibility is that the KeyFile files on different +machines do not contain the same keys. In this case, communications +among server processes themselves become impossible. For instance, +AFS's replicated database mechanism (Ubik) breaks down if the instances +of a database server process on the different database server machines are not +using the same key. +

The appearance of the following error message when you direct a +bos command to a file server machine in the local cell is one +possible symptom of server encryption key mismatch. (Note, however, +that you can also get this message if you forget to include the +-cell argument when directing the bos command to a file +server machine in a foreign cell.) +

   bos: failed to contact host's bosserver (security object was passed a bad ticket).
+

The solution to server encryption key emergencies is to put a new AFS +server encryption key in both the Authentication Database and the +KeyFile file on every server machine, so that the TGS and all +server processes again share the same key. +

Handling key emergencies requires some unusual actions. The reasons +for these actions are explained in the following sections; the actual +procedures appear in the subsequent instructions. +

Prevent Mutual Authentication

It is necessary to prevent the server processes from trying +to mutually authenticate with you as you deal with a key emergency, because +they possibly cannot decrypt your token. When you do not mutually +authenticate, the server processes assign you the identity +anonymous. To prevent mutual authentication, use the +unlog command to discard your tokens and include the +-noauth flag on every command where it is available. +

Disable Authorization Checking by Hand

Because the server processes recognize you as the user +anonymous when you do not mutually authenticate, you must turn off +authorization checking. Only with authorization checking disabled do +the server processes allow the anonymous user to perform privileged +actions such as key creation. +

In an emergency, disable authorization checking by creating the file +/usr/afs/local/NoAuth by hand. In normal circumstances, use +the bos setauth command instead. +

Work Quickly on Each Machine

Disabling authorization checking is a serious security exposure, +because server processes on the affected machine perform any action for +anyone. Disable authorization checking only for as long as necessary, +completing all steps in an uninterrupted session and as quickly as +possible. +

Work at the Console

Working at the console of each server machine on which you disable +authorization checking ensures that no one else logs onto the console while +you are working there. It does not prevent others from connecting to +the machine remotely (using the telnet program, for example), which +is why it is important to work quickly. The only way to ensure complete +security is to disable network traffic, which is not a viable option in many +environments. You can improve security in general by limiting the +number of people who can connect remotely to your server machines at any time, +as recommended in Improving Security in Your Cell. +

Change Individual KeyFile Files

If you use the Update Server to distribute the contents of +the /usr/afs/etc directory, an emergency is the only time when it +is appropriate to change the KeyFile file on individual machines +instead. Updating each machine's file is necessary because +mismatched keys can prevent the system control machine's +upserver process from mutually authenticating with +upclientetc processes on other server machines, in which case the +upserver process refuses to distribute its KeyFile file +to them. +

Even if it appears that the Update Server is working correctly, the only +way to verify that is to change the key on the system control machine and wait +the standard delay period to see if the upclientetc processes +retrieve the key. During an emergency, it does not usually make sense +to wait the standard delay period. It is more efficient simply to +update the file on each server machine separately. Also, even if the +Update Server can distribute the file correctly, other processes can have +trouble because of mismatched keys. The following instructions add the +new key file on the system control machine first. If the Update Server +is working, then it is distributing the same change as you are making on each +server machine individually. +

If your cell does not use the Update Server, or uses the international +edition of AFS, you always change keys on server machines individually. +The following instructions are also appropriate for you. +

Two Component Procedures

There are two subprocedures used frequently in the following +instructions: disabling authorization checking and reenabling it. +For the sake of clarity, the procedures are detailed here; the +instructions refer to them as necessary. +

Disabling Authorization Checking in an Emergency

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+ +
Create the file /usr/afs/local/NoAuth to disable +authorization checking. +
```
   # touch /usr/afs/local/NoAuth
+
```
+ +
Discard your tokens, in case they were sealed with an incompatible key, +which can prevent some commands from executing. +
```
   # unlog
+
```
+

Reenabling Authorization Checking in an Emergency

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Remove the /usr/afs/local/NoAuth file. +
```
   # rm /usr/afs/local/NoAuth
+
```
+ +
Authenticate as an administrative identity that belongs to the +system:administrators group and is listed in the +/usr/afs/etc/UserList file. +
```
   # klog <admin_user>
+   Password: <admin_password>
+
```
+
If appropriate, log out from the console (or close the remote connection +you are using), after issuing the unlog command to destroy your +tokens. +

To create a new server encryption key in emergencies

On the system control machine, disable authorization +checking as instructed in Disabling Authorization Checking in an Emergency. +
Issue the bos listkeys command to display the key +version numbers already in use in the KeyFile file, as a first step +in choosing the new key's key version number. +
```
   # bos listkeys <machine name> -noauth
+
```
+
where +
+
listk +
Is the shortest acceptable abbreviation of listkeys. +
machine name +
Specifies a file server machine. +
-noauth +
Bypasses mutual authentication with the BOS Server. Include it in +case the key emergency is preventing successful mutual authentication. +
+
Choose a key version number for the new key, based on what you +learned in Step 2 plus the following requirements: +
- It is best to keep your key version numbers in sequence by choosing a key +version number one greater than the largest existing one. +
- Key version numbers must be integers between 0 and 255 to comply with +Kerberos standards. +
- Do not reuse a key version number currently listed in the +KeyFile file. +
+ +
On the system control machine, issue the bos +addkey command to create a new AFS server encryption key in the +KeyFile file. +
```
   # bos addkey <machine name> -kvno <key version number> -noauth
+   input key: afs_password
+   Retype input key: afs_password
+
```
+
where +
+
addk +
Is the shortest acceptable abbreviation of addkey. +
machine name +
Names the file server machine on which to define the new key in the +KeyFile file. +
-kvno +
Specifies the key version number you chose in Step 3, an integer in the range 0 (zero) through 255. You +must specify the same number in Steps 7, 8, and 13. +
-noauth +
Bypasses mutual authentication with the BOS Server. Include it in +case the key emergency is preventing successful mutual authentication. +
afs_password +
Is a character string similar to a user password, of any length from one +to about 1,000 characters. To improve security, make the string as long +as is practical, and include nonalphabetic characters. +
Do not type an octal string directly. The BOS Server scrambles the +character string into an octal string appropriate for use as an encryption key +before recording it in the KeyFile file. +
Remember the string. You need to use it again in Steps 7, 8, and 13. +
+
On every database server machine in your cell (other +than the system control machine), disable authorization checking as instructed +in Disabling Authorization Checking in an Emergency. Do not repeat the procedure on the system control +machine, if it is a database server machine, because you already disabled +authorization checking in Step 1. (If you need to learn which machines are database +server machines, use the bos listhosts command as described in To locate database server machines.) +
Wait at least 90 seconds after finishing Step 5, to allow each of the database server processes (the +Authentication, Backup, Protection and Volume Location Servers) to finish +electing a new sync site. Then issue the udebug command to +verify that the election worked properly. Issue the following commands, +substituting each database server machine's name for server +machine in turn. Include the system control machine if it is a +database server machine. +
```
   # udebug <server machine> buserver
+   # udebug <server machine> kaserver
+   # udebug <server machine> ptserver
+   # udebug <server machine> vlserver
+
```
+
For each process, the output from all of the database server machines must +agree on which one is the sync site for the process. It is not, +however, necessary that the same machine serves as the sync site for each of +the four processes. For each process, the output from only one machine +must include the following string: +
```
   I am sync site ...
+
```
+
The output on the other machines instead includes the following line +
```
   I am not sync site
+
```
+
and a subsequent line that begins with the string Sync host and +specifies the IP address of the machine claiming to be the sync site. +
If the output does not meet these requirements or seems abnormal in another +way, contact AFS Product Support for assistance. +
On every database server machine in your cell (other +than the system control machine), issue the bos addkey command +described in Step 4. Be sure to use the same values for +afs_password and kvno as you used in that step. + +
Issue the kas setpassword command to define the new +key in the Authentication Database's afs entry. It must +match the key you created in Step 4 and Step 7. +
```
   # kas setpassword  -name afs  -kvno <key version number> -noauth
+   new_password: afs_password
+   Verifying, please re-enter new_password: afs_password
+
```
+
where +
+
sp +
Is an acceptable alias for setpassword (setp is the +shortest acceptable abbreviation). +
-kvno +
Is the same key version number you specified in Step 4. +
afs_password +
Is the same character string you specified as afs_password in +Step 4. It does not echo visibly. +
+
On every database server machine in your cell +(including the system control machine if it is a database server machine), +reenable authorization checking as instructed in Reenabling Authorization Checking in an Emergency. If the system control machine is not a database +server machine, do not perform this procedure until Step 11. +
Repeat Step 6 to verify that each database server process has properly +elected a sync site after being restarted in Step 9. +
On the system control machine (if it is not a +database server machine), reenable authorization checking as instructed in Reenabling Authorization Checking in an Emergency. If it is a database server machine, you already +performed the procedure in Step 9. +
On all remaining (simple) file server machines, disable +authorization checking as instructed in Disabling Authorization Checking in an Emergency. +
On all remaining (simple) file server machines, +issue the bos addkey command described in Step 4. Be sure to use the same values for +afs_password and kvno as you used in that step. +
On all remaining (simple) file server machines, reenable +authorization checking as instructed in Reenabling Authorization Checking in an Emergency. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd015.htm b/doc/html/AdminGuide/auagd015.htm new file mode 100644 index 0000000..0e68f62 --- /dev/null +++ b/doc/html/AdminGuide/auagd015.htm @@ -0,0 +1,2171 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

+ + +

Administering Client Machines and the Cache Manager

This chapter describes how to administer an AFS client +machine, which is any machine from which users can access the AFS filespace +and communicate with AFS server processes. (A client machine can +simultaneously function as an AFS server machine if appropriately +configured.) An AFS client machine has the following +characteristics: +

The kernel includes the set of modifications, commonly referred to as the +Cache Manager, that enable access to AFS files and directories. You can +configure many of the Cache Manager's features to suit your users' +needs. See Overview of Cache Manager Customization. +
The /usr/vice/etc directory on the local disk stores several +configuration files. See Configuration Files in the /usr/vice/etc Directory. +
A cache stores temporary copies of data fetched from AFS file server +machines, either in machine memory or on a devoted local disk +partition. See Determining the Cache Type, Size, and Location and Setting Other Cache Parameters with the afsd program. +

To learn how to install the client functionality on a machine, see the +IBM AFS Quick Beginnings. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + + + + + + + + + + + + + + + +
Display cache size set at reboot + cat /usr/vice/etc/cacheinfo +
Display current cache size and usage + fs getcacheparms +
Change disk cache size without rebooting + fs setcachesize +
Initialize Cache Manager + afsd +
Display contents of CellServDB file + cat /usr/vice/etc/CellServDB +
Display list of database server machines from kernel memory + fs listcells +
Change list of database server machines in kernel memory + fs newcell +
Check cell's status regarding setuid + fs getcellstatus +
Set cell's status regarding setuid + fs setcell +
Set server probe interval + fs checkservers -interval +
Display machine's cell membership + cat /usr/vice/etc/ThisCell +
Change machine's cell membership + Edit /usr/vice/etc/ThisCell +
Flush cached file/directory + fs flush +
Flush everything cached from a volume + fs flushvolume +
Update volume-to-mount-point mappings + fs checkvolumes +
Display Cache Manager's server preference ranks + fs getserverprefs +
Set Cache Manager's server preference ranks + fs setserverprefs +
Display client machine addresses to register + fs getclientaddrs +
Set client machine addresses to register + fs setclientaddrs +
Control the display of warning and status messages + fs messages +
Display and change machine's system type + fs sysname +
Enable asynchronous writes + fs storebehind +
+

Overview of Cache Manager Customization

+ + + +

An AFS client machine's kernel includes a set of modifications, +commonly referred to as the Cache Manager, that enable access to +AFS files and directories and communications with AFS server processes. +It is common to speak of the Cache Manager as a process or program, and in +regular usage it appears to function like one. When configuring it, +though, it is helpful to keep in mind that this usage is not strictly +accurate. +

The Cache Manager mainly fetches files on behalf of application programs +running on the machine. When an application requests an AFS file, the +Cache Manager contacts the Volume Location (VL) Server to obtain a list of the +file server machines that house the volume containing the file. The +Cache Manager then translates the application program's system call +requests into remote procedure calls (RPCs) to the File Server running on the +appropriate machine. When the File Server delivers the file, the Cache +Manager stores it in a local cache before delivering it to the +application program. +

The File Server delivers a data structure called a callback +along with the file. (To be precise, it delivers a callback for each +file fetched from a read/write volume, and a single callback for all data +fetched from a read-only volume.) A valid callback indicates that the +Cache Manager's cached copy of a file matches the central copy maintained +by the File Server. If an application on another AFS client machine +changes the central copy, the File Server breaks the callback, and the Cache +Manager must retrieve the new version when an application program on its +machine next requests data from the file. As long as the callback is +unbroken, however, the Cache Manager can continue to provide the cached +version of the file to applications on its machine, which eliminates +unnecessary network traffic. +

The indicated sections of this chapter explain how to configure and +customize the following Cache Manager features. All but the first +(choosing disk or memory cache) are optional, because AFS sets suitable +defaults for them. +

disk or memory cache. The AFS Cache Manager can use +machine memory for caching instead of space on the local disk. Deciding +which to use is the most basic configuration decision you must make. +See Determining the Cache Type, Size, and Location. +
cache size. Cache size probably has the most direct +influence on client machine performance. It determines how often the +Cache Manager must contact the File Server across the network or discard +cached data to make room for newly requested files, both of which affect how +quickly the Cache Manager delivers files to users. See Determining the Cache Type, Size, and Location. +
cache location. For a disk cache, you can alter the +conventional cache directory location (/usr/vice/cache) to take +advantage of greater space availability on other disks on the machine. +A larger cache can result in faster file delivery. See Determining the Cache Type, Size, and Location. +
chunk size and number. The afsd program, +which initializes the Cache Manager, allows you to control the size and number +of chunks into which a cache is divided, plus related parameters. +Setting these parameters is optional, because there are reasonable defaults, +but it provides precise control. The AFS distribution includes +configuration scripts that set Cache Manager parameters to values that are +reasonable for different configurations and usage patterns. See Setting Other Cache Parameters with the afsd program. +
knowledge of database server machines. Enable access to +a cell's AFS filespace and other services by listing the cell's +database server machines in the /usr/vice/etc/CellServDB file on +the local disk. See Maintaining Knowledge of Database Server Machines. +
setuid privilege. You can control whether the Cache +Manager allows programs from a cell to execute with setuid permission. +See Determining if a Client Can Run Setuid Programs. +
cell membership. Each client belongs to a one cell +defined by the local /usr/vice/etc/ThisCell file. Cell +membership determines the default cell in which the machine's users are +authenticated and in which AFS commands run. See Setting a Client Machine's Cell Membership. +
cached file version. AFS's system of callbacks +normally guarantees that the Cache Manager has the most current versions of +files and directories possible. Nevertheless, you can force the Cache +Manager to fetch the most current version of a file from the File Server if +you suspect that the cache contains an outdated version. See Forcing the Update of Cached Data. +
File Server and Volume Location Server preferences. The +Cache Manager sets numerical preference ranks for the interfaces on file +server machines and Volume Server (VL) machines. The ranks determine +which interface the Cache Manager first attempts to use when fetching data +from a volume or from the Volume Location Database (VLDB). The Cache +Manager sets default ranks as it initializes, basing them on its network +proximity to each interface, but you can modify the preference ranks if you +wish. See Maintaining Server Preference Ranks. +
interfaces registered with the File Server. If the Cache +Manager is multihomed (has multiple interface addresses), you can control +which of them it registers for File Servers to use when they initiate RPCs to +the client machine. See Managing Multihomed Client Machines. +
display of information messages. By default, the Cache +Manager sends basic error and informational messages to the client +machine's console and to command shells. You can disable the +messaging. See Controlling the Display of Warning and Informational Messages. +
system type. The Cache Manager records the local +machine's AFS system type in kernel memory, and substitutes the value for +the @sys variable in pathnames. See Displaying and Setting the System Type Name. +
delayed writes. By default, the Cache Manager writes all +data to the File Server immediately and synchronously when an application +program closes a file. You can enable asynchronous writes, either for +an individual file, or all files that the Cache Manager handles, and set how +much data remains to be written when the Cache Manager returns control to the +closing application. See Enabling Asynchronous Writes. +

You must make all configuration changes on the client machine itself (at +the console or over a direct connection such as a telnet +connection). You cannot configure the Cache Manager remotely. +You must be logged in as the local superuser root to issue some +commands, whereas others require no privilege. All files mentioned in +this chapter must actually reside on the local disk of each AFS client machine +(they cannot, for example, be symbolic links to files in AFS). +

AFS's package program can simplify other aspects of client +machine configuration, including those normally set in the machine's AFS +initialization file. See Configuring Client Machines with the package Program. +

Configuration and Cache-Related Files on the Local Disk

+ + + + + +

This section briefly describes the client configuration files that must +reside in the local /usr/vice/etc directory on every client +machine. If the machine uses a disk cache, there must be a partition +devoted to cache files; by convention, it is mounted at the +/usr/vice/cache directory. +

Configuration Files in the /usr/vice/etc Directory

The /usr/vice/etc directory on a client +machine's local disk must contain certain configuration files for the +Cache Manager to function properly. They control the most basic aspects +of Cache Manager configuration. +

If it is important that the client machines in your cell perform uniformly, +it is most efficient to update these files from a central source. The +following descriptions include pointers to sections that discuss how best to +maintain the files. +

afsd +

The binary file for the program that initializes the Cache Manager. +It must run each time the machine reboots in order for the machine to remain +an AFS client machine. The program also initializes several daemons +that improve Cache Manager functioning, such as the process that handles +callbacks. + + +

cacheinfo +

A one-line file that sets the cache's most basic configuration +parameters: the local directory at which the Cache Manager mounts the +AFS filespace, the local disk directory to use as the cache, and how many +kilobytes to allocate to the cache. +

The IBM AFS Quick Beginnings explains how to create this file as +you install a client machine. To change the cache size on a machine +that uses a memory cache, edit the file and reboot the machine. On a +machine that uses a disk cache, you can change the cache size without +rebooting by issuing the fs setcachesize command. For +instructions, see Determining the Cache Type, Size, and Location. + + +

CellServDB +

This ASCII file names the database server machines in the local cell and +in any foreign cell to which you want to enable access from this +machine. (Database server machines are the machines in a cell that run +the Authentication, Backup, Protection, and VL Server processes; see Database Server Machines.) +

The Cache Manager must be able to reach a cell's database server +machines to fetch files from its filespace. Incorrect or missing +information in the CellServDB file can slow or completely block +access. It is important to update the file whenever a cell's +database server machines change. +

As the afsd program initializes the Cache Manager, it loads the +contents of the file into kernel memory. The Cache Manager does not +read the file between reboots, so to incorporate changes to the file into +kernel memory, you must reboot the machine. Alternatively, you can +issue the fs newcell command to insert the changes directly into +kernel memory without changing the file. It can also be convenient to +upgrade the file from a central source. For instructions, see Maintaining Knowledge of Database Server Machines. +

(The CellServDB file on client machines is not the same as the +one kept in the /usr/afs/etc directory on server machines, which +lists only the local cell's database server machines. For +instructions on maintaining the server CellServDB file, see Maintaining the Server CellServDB File). + + +

NetInfo +

This optional ASCII file lists one or more of the network interface +addresses on the client machine. If it exists when the Cache Manager +initializes, the Cache Manager uses it as the basis for the list of interfaces +that it registers with File Servers. See Managing Multihomed Client Machines. + + +

NetRestrict +

This optional ASCII file lists one or more network interface +addresses. If it exists when the Cache Manager initializes, the Cache +Manager removes the specified addresses from the list of interfaces that it +registers with File Servers. See Managing Multihomed Client Machines. + + +

ThisCell +

This ASCII file contains a single line that specifies the complete +domain-style name of the cell to which the machine belongs. Examples +are abc.com and stateu.edu. This +value defines the default cell in which the machine's users become +authenticated, and in which the command interpreters (for example, the +bos command) contact server processes. +

The IBM AFS Quick Beginnings explains how to create this file as +you install the AFS client functionality. To learn about changing a +client machine's cell membership, see Setting a Client Machine's Cell Membership. +

In addition to these files, the /usr/vice/etc directory also +sometimes contains the following types of files and subdirectories: +

The AFS initialization script, called afs.rc on many +system types. In the conventional configuration specified by the +IBM AFS Quick Beginnings, it is a symbolic link to the actual +script kept in the same directory as other initialization files used by the +operating system. + + +
A subdirectory that houses AFS kernel library files used by a dynamic +kernel loading program. + + +
A subdirectory called C, which houses the Cache Manager catalog +file called afszcm.cat. The fstrace program uses the +catalog file to translate operation codes into character strings, which makes +the message in the trace log more readable. See About the fstrace Command Suite. +

Cache-Related Files

+ + + + + +

A client machine that uses a disk cache must have a local disk directory +devoted to the cache. The conventional mount point is +/usr/vice/cache, but you can use another partition that has more +available space. +

Do not delete or directly modify any of the files in the cache +directory. Doing so can cause a kernel panic, from which the only way +to recover is to reboot the machine. By default, only the local +superuser root can read the files directly, by virtue of owning +them. +

A client machine that uses a memory cache keeps all of the information +stored in these files in machine memory instead. +

CacheItems +: A binary-format file in which the Cache Manager tracks the contents of +cache chunks (the V files in the directory, described just +following), including the file ID number (fID) and the data version +number. + + +
VolumeItems +: A binary-format file in which the Cache Manager records the mapping +between mount points and the volumes from which it has fetched data. +The Cache Manager uses the information when responding to the pwd +command, among others. + + + +
Vn +: A cache chunk file, which expands to a maximum size (by default, 64 KB) to +house data fetched from AFS files. The number of Vn +files in the cache depends on the cache size among other factors. The +n is the index assigned to each file; they are numbered +sequentially, but the Cache Manager does not necessarily use them in order or +contiguously. If an AFS file is larger than the maximum size for +Vn files, the Cache Manager divides it across multiple +Vn files. +

Determining the Cache Type, Size, and Location

This section explains how to configure a memory or disk +cache, how to display and set the size of either type of cache, and how to set +the location of the cache directory for a disk cache. + + +

The Cache Manager uses a disk cache by default, and it is the preferred +type of caching. To configure a memory cache, include the +-memcache flag on the afsd command, which is normally +invoked in the machine's AFS initialization file. If configured to +use a memory cache, the Cache Manager does no disk caching, even if the +machine has a disk. +

Choosing the Cache Size

+ +

Cache size influences the performance of a client machine more directly +than perhaps any other cache parameter. The larger the cache, the +faster the Cache Manager is likely to deliver files to users. A small +cache can impair performance because it increases the frequency at which the +Cache Manager must discard cached data to make room for newly requested +data. When an application asks for data that has been discarded, the +Cache Manager must request it from the File Server, and fetching data across +the network is almost always slower than fetching it from the local +disk. The Cache Manager never discards data from a file that has been +modified locally but not yet stored back to the File Server. If the +cache is very small, the Cache Manager possible cannot find any data to +discard. For more information about the algorithm it uses when +discarding cached data, see How the Cache Manager Chooses Data to Discard). +

The amount of disk or memory you devote to caching depends on several +factors. The amount of space available in memory or on the partition +housing the disk cache directory imposes an absolute limit. In +addition, you cannot allocate more than 95% of the space available on the +cache directory's partition to a disk cache. The afsd +program exits without starting the Cache Manager and prints an appropriate +message to the standard output stream if you violate this restriction. +For a memory cache, you must leave enough memory for other processes and +applications to run. If you try to allocate more memory than is +actually 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. +

Within these hard limits, the factors that determine appropriate cache size +include the number of users working on the machine, the size of the files with +which they usually work, and (for a memory cache) the number of processes that +usually run on the machine. The higher the demand from these factors, +the larger the cache needs to be to maintain good performance. +

Disk caches smaller than 10 MB do not generally perform well. +Machines serving multiple users usually perform better with a cache of at +least 60 to 70 MB. The point at which enlarging the cache further does +not really improve performance depends on the factors mentioned previously, +and is difficult to predict. +

Memory caches smaller than 1 MB are nonfunctional, and the performance of +caches smaller than 5 MB is usually unsatisfactory. Suitable upper +limits are similar to those for disk caches but are probably determined more +by the demands on memory from other sources on the machine (number of users +and processes). Machines running only a few processes possibly can use +a smaller memory cache. +

AFS imposes an absolute limit on cache size in some versions. See +the IBM AFS Release Notes for the version you are using. +

Displaying and Setting the Cache Size and Location

+ + + + + + + + + + + + + + + + + + + + + +

The Cache Manager determines how big to make the cache by reading the +/usr/vice/etc/cacheinfo file as it initializes. As directed +in the IBM AFS Quick Beginnings, you must create the file before +running the afsd program. The file also defines the +directory on which to mount AFS (by convention, /afs), and the +local disk directory to use for a cache directory. +

To change any of the values in the file, log in as the local superuser +root. You must reboot the machine to have the new value take +effect. For instructions, see To edit the cacheinfo file. +

To change the cache size at reboot without editing the cacheinfo +file, include the -blocks argument to the afsd +command; see the command's reference page in the IBM AFS +Administration Reference. +

For a disk cache, you can also use the fs setcachesize command +to reset the cache size without rebooting. The value you set persists +until the next reboot, at which time the cache size returns to the value +specified in the cacheinfo file or by the -blocks +argument to the afsd command. For instructions, see To change the disk cache size without rebooting. +

To display the current cache size and the amount of space the Cache Manager +is using at the moment, use the fs getcacheparms command as +detailed in To display the current cache size. +

To display the cache size set at reboot

Use a text editor or the cat command to display the contents of +the /usr/vice/etc/cacheinfo file. +
```
   % cat /usr/vice/etc/cacheinfo
+
```
+

+ + + + + + +

To display the current cache size

Issue the fs getcacheparms command on the client +machine. +
```
   % fs getcacheparms
+
```
+
where getca is the shortest acceptable abbreviation of +getcacheparms. +
The output shows the number of kilobyte blocks the Cache Manager is using +as a cache at the moment the command is issued, and the current size of the +cache. For example: +
```
   AFS using 13709 of the cache's available 15000 1K byte blocks.
+
```
+

+ + + + + +

To edit the cacheinfo file

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Use a text editor to edit the /usr/vice/etc/cacheinfo file, +which has three fields, separated by colons: +
- The first field names the local directory on which to mount the AFS +filespace. The conventional location is /afs. +
- The second field defines the local disk directory to use for the disk +cache. The conventional location is the /usr/vice/cache +directory, but you can specify an alternate directory if another partition has +more space available. There must always be a value in this field, but +the Cache Manager ignores it if the machine uses a memory cache. +
- The third field defines cache size as a number of kilobyte (1024-byte) +blocks. +
+
The following example mounts the AFS filespace at the /afs +directory, names /usr/vice/cache as the cache directory, and sets +cache size to 50,000 KB: +
```
   /afs:/usr/vice/cache:50000
+
```
+

+ + + + + + +

To change the disk cache size without rebooting

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs setcachesize command to set a new disk +cache size. +
Note: This command does not work for a memory cache. +
+
```
   # fs setcachesize <size in 1K byte blocks (0 => reset)>
+
```
+
where +
+
setca +
Is the shortest acceptable abbreviation of setcachesize. +
size in 1K byte blocks (0 => reset) +
Sets the number of kilobyte blocks to be used for the cache. +Specify a positive integer (1024 equals 1 MB), or 0 +(zero) to reset the cache size to the value specified in the +cacheinfo file. +
+

+ + + + + + +

To reset the disk cache size to the default without rebooting

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs setcachesize command to reset the size of the +local disk cache (the command does not work for a memory cache). Choose +one of the two following options: +
- To reset the cache size to the value specified in the local +cacheinfo file, specify the value 0 (zero) +
```
   # fs setcachesize 0
+
```
  +
- To reset the cache size to the value set at the last reboot of the +machine, include the -reset flag. Unless the +-blocks argument was used on the afsd command, this is +also the value in the cacheinfo file. +
```
   # fs setcachesize -reset
+
```
  +
+
where +
+
setca +
Is the shortest acceptable abbreviation of setcachesize. +
0 +
Resets the disk cache size to the value in the third field of the +/usr/vice/etc/cacheinfo file. +
-reset +
Resets the cache size to the value set at the last reboot. +
+

How the Cache Manager Chooses Data to Discard

When the cache is full and application programs request more +data from AFS, the Cache Manager must flush out cache chunks to make room for +the data. The Cache Manager considers two factors: +

How recently an application last accessed the data. +
Whether the chunk is dirty. A dirty chunk contains +changes to a file that have not yet been saved back to the permanent copy +stored on a file server machine. +

The Cache Manager first checks the least-recently used chunk. If it +is not dirty, the Cache Manager discards the data in that chunk. If the +chunk is dirty, the Cache Manager moves on to check the next least recently +used chunk. It continues in this manner until it has created a +sufficient number of empty chunks. +

Chunks that contain data fetched from a read-only volume are by definition +never dirty, so the Cache Manager can always discard them. Normally, +the Cache Manager can also find chunks of data fetched from read/write volumes +that are not dirty, but a small cache makes it difficult to find enough +eligible data. If the Cache Manager cannot find any data to discard, it +must return I/O errors to application programs that request more data from +AFS. Application programs usually have a means for notifying the user +of such errors, but not for revealing their cause. +

Setting Other Cache Parameters with the afsd program

There are only three cache configuration parameters you must +set: the mount directory for AFS, the location of the disk cache +directory, and the cache size. They correspond to the three fields in +the /usr/vice/etc/cacheinfo file, as discussed in Determining the Cache Type, Size, and Location. However, if you want to experiment with fine-tuning +cache performance, you can use the arguments on the afsd command to +control several other parameters. This section discusses a few of these +parameters that have the most direct effect on cache performance. To +learn more about the afsd command's arguments, see its +reference page in the IBM AFS Administration Reference. +

In addition, the AFS initialization script included in the AFS distribution +for each system type includes several variables that set several +afsd arguments in a way that is suitable for client machines of +different sizes and usage patterns. For instructions on using the +script most effectively, see the section on configuring the Cache Manager in +the IBM AFS Quick Beginnings. +

Setting Cache Configuration Parameters

The cache configuration parameters with the most direct +effect on cache performance include the following: +

total cache size. This is the amount of disk space or +machine memory available for caching, as discussed in detail in Determining the Cache Type, Size, and Location. +
number of cache chunks. For a disk cache, each chunk is +a Vn file in the local cache directory (see Cache-Related Files). For a memory cache, each chunk is a set of +contiguous blocks allocated in machine memory. +
This parameter does not have as much of an effect on cache performance as +total size. However, adjusting it can influence how often the Cache +Manager must discard cached data to make room for new data. Suppose, +for example, that you set the disk cache size to 50 MB and the number of +chunks (Vn files) to 1,000. If each of the ten +users on the machine caches 100 AFS files that average 20 KB in size, then all +1,000 chunks are full (a chunk can contain data from only one AFS file) but +the cache holds only about 20 MB of data. When a user requests more +data from the File Server, the Cache Manager must discard cached data to +reclaim some chunks, even though the cache is filled to less than 50% of its +capacity. In such a situation, increasing the number of chunks enables +the Cache Manager to discard data less often. +
chunk size. This parameter determines the maximum amount +of data that can fit in a chunk. If a cached element is smaller than +the chunk size, the remaining space in the chunk is not used (a chunk can hold +no more than one element). If an element cannot fit in a single chunk, +it is split across as many chunks as needed. This parameter also +determines how much data the Cache Manager requests at a time from the File +Server (how much data per fetch RPC, because AFS uses partial file +transfer). +
The main reason to change chunk size is because of its relation to the +amount of data fetched per RPC. If your network links are very fast, it +can improve performance to increase chunk size; if the network is +especially slow, it can make sense to decrease chunk size. +
number of dcache entries in memory. The Cache Manager +maintains one dcache entry for each cache chunk, recording a small amount of +information, such as the file ID (fID) and version number of the AFS file +corresponding to the chunk. +
For a disk cache, dcache entries reside in the +/usr/vice/cache/CacheItems file; a small number are duplicated +in machine memory to speed access. +
For a memory cache, the number of dcache entries equals the number of cache +chunks. For a discussion of the implications of this correspondence, +see Controlling Memory Cache Configuration. +

For a description of how the Cache Manager determines defaults for number +of chunks, chunk size, and number of dcache entries in a disk cache, see Configuring a Disk Cache; for a memory cache, see Controlling Memory Cache Configuration. The instructions also explain +how to use the afsd command's arguments to override the +defaults. +

Configuring a Disk Cache

The default number of cache chunks (Vn +files) in a disk cache is calculated by the afsd command to be the +greatest of the following: +

100 +
1.5 times the result of dividing cache size by chunk size +(cachesize/chunksize * 1.5) +
The result of dividing cachesize by 10 MB (cachesize/10240) +

You can override this value by specifying a positive integer with the +-files argument. Consider increasing this value if more than +75% of the Vn files are already used soon after the Cache +Manager finishes initializing. Consider decreasing it if only a small +percentage of the chunks are used at that point. In any case, never +specify a value less than 100, because a smaller value can cause performance +problems. +

The following example sets the number of Vn files to +2,000: +

   /usr/vice/etc/afsd -files 2000
+

Note:

It is conventional to place the afsd command in a machine's +AFS initialization file, rather than entering it in a command shell. +Furthermore, the values specified in this section are examples only, and are +not necessarily suitable for a specific machine. +

The default chunk size for a disk cache is 64 KB. In general, the +only reason to change it is to adjust to exceptionally slow or fast +networks; see Setting Cache Configuration Parameters. You can use the -chunksize +argument to override the default. Chunk size must be a power of 2, so +provide an integer between 0 (zero) and 30 to be used as an exponent of +2. For example, a value of 10 sets chunk size to 1 KB (2¹⁰ = +1024); a value of 16 equals the default for disk caches (2¹⁶ = +64 KB). Specifying a value of 0 (zero) or greater than 30 returns chunk +size to the default. Values less than 10 (1 KB) are not +recommended. The following example sets chunk size to 16 KB +(2¹⁴): +

   /usr/vice/etc/afsd -chunksize 14
+

For a disk cache, the default number of dcache entries duplicated in memory +is one-half the number of chunks specified with the -files +argument, to a maximum of 2,000 entries. You can use the +-dcache argument to change the default, even exceeding 2,000 if you +wish. Duplicating more than half the dcache entries in memory is not +usually necessary, but sometimes improves performance slightly, because access +to memory is faster than access to disk. The following example sets the +number to 750: +

   /usr/vice/etc/afsd -dcache 750
+

When configuring a disk cache, you can combine the afsd +command's arguments in any way. The main reason for this +flexibility is that the setting you specify for disk cache size (in the +cacheinfo file or with the -blocks argument) is an +absolute maximum limit. You cannot override it by specifying higher +values for the -files or -chunksize arguments, alone or +in combination. A related reason is that the Cache Manager does not +have to reserve a set amount of memory on disk. Vn +files (the chunks in a disk cache) are initially zero-length, but can expand +up to the specified chunk size and shrink again, as needed. If you set +the number of Vn files to such a large value that +expanding all of them to the full allowable size exceeds the total cache size, +they simply never grow to full size. +

Controlling Memory Cache Configuration

Configuring a memory cache differs from configuring a disk +cache in that not all combinations of the afsd command's +arguments are allowed. This limitation results from the greater +interaction between the configuration parameters in a memory cache than a disk +cache. If all combinations are allowed, it is possible to set the +parameters in an inconsistent way. A list of the acceptable and +unacceptable combinations follows a discussion of default values. +

The default chunk size for a memory cache is 8 KB. In general, the +only reason to change it is to adjust to exceptionally slow or fast +networks; see Setting Cache Configuration Parameters. +

There is no predefined default for number of chunks in a memory +cache. The Cache Manager instead calculates the correct number by +dividing the total cache size by the chunk size. Recall that for a +memory cache, all dcache entries must be in memory. This implies that +the number of chunks equals the number of dcache entries in memory, and that +there is no default for number of dcache entries (like the number of chunks, +it is calculated by dividing the total size by the chunk size). +

The following are acceptable combinations of the afsd +command's arguments when configuring a memory cache: +

-blocks alone, which overrides the cache size specified in the +/usr/vice/etc/cacheinfo file. The Cache Manager divides the +value of this argument by the default chunk size of eight KB to calculate the +number of chunks and dcache entries. The following example sets cache +size to five MB (5,120 KB) and the number of chunks to 640 (5,120 divided by +8): +
```
   /usr/vice/etc/afsd -memcache -blocks 5120
+
```
+
-chunksize alone, to override the default of eight KB. +The chunk size must be a power of two, so provide an integer between 0 (zero) +and 30 to be used as an exponent of two. For example, a value of ten +sets chunk size to 1 KB (2¹⁰ = 1024); a value of 13 equals the +default for memory caches (2¹³ = 8 KB). Specifying a value +of 0 (zero) or greater than 30 returns the chunk size to the default. +Values less than ten (equivalent to 1 KB) are not recommended. The +following example sets the chunk size to four KB (2¹²). +Assuming a total cache size of four MB (4,096 KB), the resulting number of +chunks is 1024. +
```
   /usr/vice/etc/afsd -memcache -chunksize 12
+
```
+
-blocks and -chunksize together override the +defaults for cache size and chunk size. The Cache Manager divides the +first by the second to calculate the number of chunks and dcache +entries. For example, the following example sets the cache size to six +MB (6,144 KB) and chunksize to four KB (2¹²), resulting in 1,536 +chunks: +
```
   /usr/vice/etc/afsd -memcache -blocks 6144 -chunksize 12
+
```
+

The following arguments or combinations explicitly set the number of chunks +and dcache entries. It is best not to use them, because they set the +cache size indirectly, forcing you to perform a hand calculation to determine +the size of the cache. Instead, set the -blocks and +-chunksize arguments alone or in combination; in those cases, +the Cache Manager determines the number of chunks and dcache entries +itself. Because the following combinations are not recommended, no +examples are included. +

The -dcache argument alone explicitly sets the number of chunks +and dcache entries. The Cache Manager multiples this value times the +default chunk size of 8 KB to derive the total cache size (overriding the +value in the cacheinfo file). +
The combination of -dcache and -chunksize sets the +chunk number and size. The Cache Manager sets the specified values and +multiplies them together to obtain total cache size (overriding the value in +the cacheinfo file). +

Do not use the following arguments for a memory cache: +

-files alone. This argument controls the number of +Vn files for a disk cache, but is ignored for a memory +cache. +
-blocks and -dcache. An error message +results, because it is possible to provide values such that dividing the first +(total size) by the second (number of chunks) results in a chunk size that is +not a power of two. +

Maintaining Knowledge of Database Server Machines

+ + + + + + + + + +

For the users of an AFS client machine to access a cell's AFS +filespace and other services, the Cache Manager and other client-side agents +must have an accurate list of the cell's database server machines. +The affected functions include the following: +

Accessing files. The Cache Manager contacts the Volume Location +(VL) Server to learn which file server machine houses the volume containing a +requested file or directory. If the Cache Manager cannot contact a +cell's VL Servers, it cannot fetch files. +
Authenticating. The klog program and AFS-modified login +utilities contact the Authentication Server to obtain tokens, 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. +
Editing access control lists (ACLs). The fs command +interpreter contacts the File Server that maintains the read/write volume +containing a file or directory; the location information comes from the +VL Server. +

To enable a machine's users to access a cell, you must list the names +and IP addresses of its database server machines in the +/usr/vice/etc/CellServDB file on the machine's local +disk. In addition to the machine's home cell, you can list any +foreign cells that you want to enable users to access. (To enable +access to a cell's filespace, you must also mount its +root.cell volume in the local AFS filespace; the +conventional location is just under the AFS root directory, +/afs. For instructions, see the IBM AFS Quick +Beginnings.) +

How Clients Use the List of Database Server Machines

As the afsd program runs and initializes the Cache Manager, +it reads the contents of the CellServDB file into kernel +memory. The Cache Manager does not consult the file again until the +machine next reboots. In contrast, the command interpreters for the AFS +command suites (such as fs and pts) read the +CellServDB file each time they need to contact a database server +process. +

When a cell's list of database server machines changes, you must +change both the CellServDB file and the list in kernel memory to +preserve consistent client performance; some commands probably fail if +the two lists of machines disagree. One possible method for updating +both the CellServDB file and kernel memory is to edit the file and +reboot the machine. To avoid needing to reboot, you can instead perform +both of the following steps: +

Issue the fs newcell command to alter the list in kernel memory +directly, making the changes available to the Cache Manager. +
Edit the CellServDB file to make the changes available to +command interpreters. For a description of the file's format, see The Format of the CellServDB file. +

The consequences of missing or incorrect information in the +CellServDB file or kernel memory are as follows: +

If there is no entry for a cell, the machine's users cannot access +the cell. +
If a cell's entry does not include a database server machine, then +the Cache Manager and command interpreters never attempt to contact the +machine. The omission does not prevent access to the cell--as long +as the information about the other database server machines is correct and the +server processes, machines, and network are functioning correctly--but it +can put an undue burden on the machines that are listed. If all of the +listed machines become inaccessible to clients, then the cell becomes +inaccessible even if the omitted database server machine is functioning +correctly. +
If a machine's name or address is incorrect, or the machine is not +actually running the database server processes, then requests from clients +time out. Users can experience lengthy delays because they have to wait +the full timeout period before the Cache Manager or command interpreter +contacts another database server machine. +

The Format of the CellServDB file

+ + +

When editing the /usr/vice/etc/CellServDB file, you must use the +correct format for cell and machine entries. Each cell has a separate +entry. The first line has the following format: +

   >cell_name      #organization
+

where cell_name is the cell's complete Internet domain name +(for example, abc.com) and organization is an +optional field that follows any number of spaces and the number sign +(#) and can name the organization to which the cell corresponds +(for example, the ABC Corporation). After the first line comes a +separate line for each database server machine. Each line has the +following format: +

   IP_address   #machine_name
+

where IP_address is the machine's IP address in dotted +decimal format (for example, 192.12.105.3). +Following any number of spaces and the number sign (#) is +machine_name, the machine's fully-qualified hostname (for +example, db1.abc.com). In this case, the +number sign does not indicate a comment: machine_name is a +required field. +

The order in which the cells appear is not important, but it is convenient +to put the client machine's home cell first. Do not include any +blank lines in the file, not even after the last entry. +

The following example shows entries for two cells, each of which has three +database server machines: +

   >abc.com       #ABC Corporation (home cell)
+   192.12.105.3      #db1.abc.com
+   192.12.105.4      #db2.abc.com
+   192.12.105.55     #db3.abc.com
+   >stateu.edu    #State University cell
+   138.255.68.93     #serverA.stateu.edu
+   138.255.68.72     #serverB.stateu.edu
+   138.255.33.154    #serverC.stateu.edu
+

Maintaining the Client CellServDB File

+ + +

Because a correct entry in the CellServDB file is vital for +consistent client performance, you must also update the file on each client +machine whenever a cell's list of database server machines changes (for +instance, when you follow the instructions in the IBM AFS Quick +Beginnings to add or remove a database server machine). To +facilitate the client updates, you can use the package program, +which copies files from a central source in AFS to the local disk of client +machines. It is conventional to invoke the package program +in a client machine's AFS initialization file so that it runs as the +machine reboots, but you can also issue the package command at any +time. For instructions, see Running the package program. +

If you use the package program, the conventional location for +your cell's central source CellServDB file is +/afs/cell_name/common/etc/CellServDB, where +cell_name is your cell name. + +

Creating a symbolic or hard link from /usr/vice/etc/CellServDB +to a central source file in AFS is not a viable option. The +afsd program reads the file into kernel memory before the Cache +Manager is completely initialized and able to access AFS. +

Because every client machine has its own copy of the CellServDB +file, you can in theory make the set of accessible cells differ on various +machines. In most cases, however, it is best to maintain consistency +between the files on all client machines in the cell: differences +between machines are particularly confusing if users commonly use a variety of +machines rather than just one. +

The AFS Product Support group maintains a central CellServDB +file that includes all cells that have agreed to make their database server +machines access to other AFS cells. It is advisable to check this file +periodically for updated information. See Making Your Cell Visible to Others. + +

An entry in the local CellServDB is one of the two requirements +for accessing a cell. The other is that the cell's +root.cell volume is mounted in the local filespace, by +convention as a subdirectory of the /afs directory. For +instructions, see To create a cellular mount point. +
Note: The /usr/vice/etc/CellServDB file on a client machine is not the +same as the /usr/afs/etc/CellServDB file on the local disk of a +file server machine. The server version lists only the database server +machines in the server machine's home cell, because server processes +never need to contact foreign cells. It is important to update both +types of CellServDB file on all machines in the cell whenever there +is a change to your cell's database server machines. For more +information about maintaining the server version of the CellServDB +file, see Maintaining the Server CellServDB File. +
+ + + + + +

To display the /usr/vice/etc/CellServDB file

Use a text editor or the cat command to display the contents of +the /usr/vice/etc/CellServDB file. By default, the mode bits +on the file permit anyone to read it. +
```
   % cat /usr/vice/etc/CellServDB
+
```
+

+ + +

To display the list of database server machines in kernel memory

Issue the fs listcells command. +
```
   % fs listcells [&] 
+
```
+
where listc is the shortest acceptable abbreviation of +listcells. +
To have your shell prompt return immediately, include the ampersand +(&), which makes the command run in the background. It +can take a while to generate the complete output because the kernel stores +database server machines' IP addresses only, and the fs +command interpreter has the cell's name resolution service (such as the +Domain Name Service or a local host table) translate them into +hostnames. You can halt the command at any time by issuing an interrupt +signal such as Ctrl-c. +
The output includes a single line for each cell, in the following +format: +
```
   Cell cell_name on hosts list_of_hostnames.
+
```
+
The name service sometimes returns hostnames in uppercase letters, and if +it cannot resolve a name at all, it returns its IP address. The +following example illustrates all three possibilities: +
```
   % fs listcells
+      .
+      .
+   Cell abc.com on hosts db1.abc.com db2.abc.com db3.abc.com
+   Cell stateu.edu on hosts SERVERA.STATEU.EDU SERVERB.STATEU.EDU 
+			    SERVERC.STATEU.EDU
+   Cell ghi.org on hosts 191.255.64.111 191.255.64.112
+      .
+      .
+
```
+

+ + + + + + + + + + + +

To change the list of a cell's database server machines in kernel memory

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
If you a use a central copy of the CellServDB file as a source +for client machines, verify that its directory's ACL grants you the +l (lookup), r (read), and +w (write) permissions. The conventional directory +is /afs/cell_name/common/etc. If +necessary, issue the fs listacl command, which is fully described +in Displaying ACLs. +
```
   # fs listacl [<dir/file path>]
+
```
+ + +

Issue the fs newcell command to add or change a +cell's entry in kernel memory. Repeat the command for each +cell. +

Note:

You cannot use this command to remove a cell's entry completely from +kernel memory. In the rare cases when you urgently need to prevent +access to a specific cell, you must edit the CellServDB file and +reboot the machine. +

   # fs newcell <cell name> <primary servers>⁺ \
+                [-linkedcell <linked cell name>]
+

where +

n +: Is the shortest acceptable abbreviation of newcell. +
cell name +: Specifies the complete Internet domain name of the cell for which to +record a new list of database server machines. +
primary servers +: Specifies the fully-qualified hostname or IP address in dotted-decimal +format for each database server machine in the cell. The list you +provide completely replaces the existing list. +
-linkedcell +: Specifies the complete Internet domain name of the AFS cell to link to a +DCE cell for the purposes of DFS fileset location. You can use this +argument if the machine's AFS users access DFS via the AFS/DFS Migration +Toolkit Protocol Translator. For instructions, see the IBM AFS/DFS +Migration Toolkit Administration Guide and Reference. +

Add or edit the cell's entry in the local +/usr/vice/etc/CellServDB file, using one of the following three +methods. In each case, be sure to obey the formatting requirements +described in The Format of the CellServDB file. +
- If you maintain a central source version of the CellServDB file +and use the package program, first use a text editor to alter the +central copy of the file. Then issue the package command to +transfer the contents of the file to the local machine. For complete +instructions, see Running the package program. +
```
   # /etc/package -v -c <name of package file>
+
```
  +
- If you maintain a central source CellServDB file but do not use +the package program, first use a text editor to alter the central +copy of the file. Then use a copying command such as the cp +command to copy it to the local /usr/vice/etc/CellServDB +file. +
- If you do not use a central source CellServDB file, edit the +local machine's /usr/vice/etc/CellServDB file directly. +
+

Determining if a Client Can Run Setuid Programs

+ + + +

A setuid program is one whose binary file has the UNIX setuid +mode bit turned on. While a setuid program runs, the user who +initialized it assumes the local identity (UNIX UID) of the binary file's +owner, and so is granted the permissions in the local file system that pertain +to the owner. Most commonly, the issuer's assumed identity (often +referred to as effective UID) is the local superuser +root. +

AFS does not recognize effective UID: if a setuid program accesses +AFS files and directories, it uses the current AFS identity of the user who +initialized the program, not of the program's owner. Nevertheless, +it can be useful to store setuid programs in AFS for use on more than one +client machine. AFS enables a client machine's administrator to +determine whether the local Cache Manager allows setuid programs to run or +not. +

By default, the Cache Manager allows programs from its home cell to run +with setuid permission, but denies setuid permission to programs from foreign +cells. A program belongs to the same cell as the file server machine +that houses the volume in which the file resides, as specified in the file +server machine's /usr/afs/etc/ThisCell file. The Cache +Manager determines its own home cell by reading the +/usr/vice/etc/ThisCell file at initialization. +

To change a cell's setuid status with respect to the local machine, +become the local superuser root and issue the fs setcell +command. To determine a cell's current setuid status, use the +fs getcellstatus command. +

When you issue the fs setcell command, you directly alter a +cell's setuid status as recorded in kernel memory, so rebooting the +machine is not necessary. However, nondefault settings do not persist +across reboots of the machine unless you add the appropriate fs +setcell command to the machine's AFS initialization file. +

Only members of the system:administrators group can turn +on the setuid mode bit on an AFS file or directory. When the setuid +mode bit is turned on, the UNIX ls -l command displays the third +user mode bit as an s instead of an x, but for an AFS +file or directory, the s appears only if setuid permission is +enabled for the cell in which the file resides. + + +

To determine a cell's setuid status

Issue the fs getcellstatus command to check the setuid status +of each desired cell. +
```
   % fs getcellstatus <cell name>
+
```
+
where +
+
getce +
Is the shortest acceptable abbreviation of +getcellstatus. +
cell name +
Names each cell for which to report setuid status. Provide the +complete Internet domain name or a shortened form that distinguishes it from +the other cells listed in the local /usr/vice/etc/CellServDB +file. +
+

The output reports the setuid status of each cell: +

the string no setuid allowed indicates that the Cache Manager +does not allow programs from the cell to run with setuid permission +
setuid allowed indicates that the Cache Manager allows programs +from the cell to run with setuid permission +

+ + +

To change a cell's setuid status

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs setcell command to change the setuid status of the +cell. +
```
   # fs setcell <cell name>⁺ [-suid] [-nosuid]
+
```
+
where +
+
setce +
Is the shortest acceptable abbreviation of setcell. +
cell name +
Names each cell for which to change setuid status as specified by the +-suid or -nosuid flag. Provide each cell's +complete Internet domain name or a shortened form that distinguishes it from +the other cells listed in the local /usr/vice/etc/CellServDB +file. +
-suid +
Enables programs from each specified cell to execute with setuid +permission. Provide this flag or the -nosuid flag, or omit +both to disable setuid permission for each cell. +
-nosuid +
Prevents programs from each specified cell from executing with setuid +permission. Provide this flag or the -suid flag, or omit +both to disable setuid permission for each cell. +
+

Setting the File Server Probe Interval

+ + + +

The Cache Manager periodically sends a probe to server machines to verify +that they are still accessible. Specifically, it probes the database +server machines in its cell and those file servers that house data it has +cached. +

If a server process does not respond to a probe, the client machine assumes +that it is inaccessible. By default, the interval between probes is +three minutes, so it can take up to three minutes for a client to recognize +that a server process is once again accessible after it was +inaccessible. +

To adjust the probe interval, include the -interval argument to +the fs checkservers command while logged in as the local superuser +root. The new interval setting persists until you again +issue the command or reboot the machine, at which time the setting returns to +the default. To preserve a nondefault setting across reboots, include +the appropriate fs checkservers command in the machine's AFS +initialization file. +

To set a client's file server probe interval

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs checkservers command with the -interval +argument. + + +
+
```
   # fs checkservers -interval <seconds between probes>
+
```
+
where +
+
checks +
Is the shortest acceptable abbreviation of checkservers. +
-interval +
Specifies the number of seconds between probes. Provide an integer +value greater than zero. +
+

Setting a Client Machine's Cell Membership

+ + + + + + +

Each client machine belongs to a particular cell, as named in the +/usr/vice/etc/ThisCell on its local disk. The machine's +cell membership determines three defaults important to users of the +machine: +

The cell for which users of the machine obtain tokens (authenticate) when +they use the login program or issue the klog +command. There are two effects: +
- The klog program and AFS-modified login utilities contact an +Authentication Server in the cell named in the ThisCell +file. +
- The klog program and AFS-modified login utilities combine the +contents of the ThisCell file with the password that the user +provides, generating an encryption key from the combination. The +user's entry in the Authentication Database includes an encryption key +also generated from the combination of password and cell name. If the +cell name in the ThisCell file is incorrect, users cannot +authenticate even if they provide the correct password. +
+
The cell the Cache Manager considers its local, or home, cell. The +Cache Manager allows programs from its local cell to run with setuid +permission, but not programs from foreign cells, as discussed further in Determining if a Client Can Run Setuid Programs. +
The default database server machines that are contacted by the AFS command +interpreters running on this machine. +

To display a client machine's cell membership

Use a text editor or the cat command to display the contents of +the /usr/vice/etc/ThisCell file. +
```
   % cat /usr/vice/etc/ThisCell
+
```
+

To set a client machine's cell membership

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Using a text editor, replace the cell name in the +/usr/vice/etc/ThisCell file. +
(Optional.) Reboot the machine to enable the Cache +Manager to use the new cell name immediately; the appropriate command +depends on the machine's system type. The klog program, +AFS-modified login utilities, and the AFS command interpreters use the new +cell name the next time they are invoked; no reboot is necessary. +
```
   # sync
+   
+   # shutdown
+
```
+

Forcing the Update of Cached Data

+ + + + + + + + +

AFS's callback mechanism normally guarantees that the Cache Manager +provides the most current version of a file or directory to the application +programs running on its machine. However, you can force the Cache +Manager to discard (flush) cached data so that the next time an application +program requests it, the Cache Manager fetches the latest version available at +the File Server. +

You can control how many file system elements to flush at a time: +

To flush only specific files or directories, use the fs flush +command. This command forces the Cache Manager to discard the data and +status information it has cached from the specified files or +directories. It does not discard information from an application +program's buffer or information that has been altered locally (changes +made in the cache but not yet saved permanently to the File Server). +However, the next time an application requests the element's data or +status information, the Cache Manager has to contact the File Server to get +it. +
To flush everything cached from a certain volume, use the fs +flushvolume command. This command works like the fs +flush command, but differs in two ways: +
- The Cache Manager discards data for all elements in the cache that come +from the same volume as the specified files or directories. +
- The Cache Manager discards only data, not status information. This +difference has little practical effect, but can lead to different output from +the ls command when the two different commands are used to flush +the same element. +
+

In addition to callbacks, the Cache Manager has a mechanism for tracking +other kinds of possible changes, such as changes in a volume's +location. If a volume moves and the Cache Manager has not accessed any +data in it for a long time, the Cache Manager's volume location record +can be wrong. To resynchronize it, use the fs checkvolumes +command. When you issue the command, the Cache Manager creates a new +table of mappings between volume names, ID numbers, and locations. This +forces the Cache Manager to reference newly relocated and renamed volumes +before it can provide data from them. +

It is also possible for information about mount points to become corrupted +in the cache. Symptoms of a corrupted mount point included garbled +output from the fs lsmount command, and failed attempts to change +directory to or list the contents of a mount point. Use the fs +flushmount command to discard a corrupted mount point. The Cache +Manager must refetch the mount point the next time it crosses it in a +pathname. (The Cache Manager periodically refreshes cached mount +points, but the only other way to discard them immediately is to reinitialize +the Cache Manager by rebooting the machine. + + +

To flush certain files or directories

Issue the fs flush command. +
```
   % fs flush [<dir/file path>⁺]
+
```
+
where +
+
flush +
Must be typed in full. +
dir/file path +
Names each file or directory structure to flush from the cache. +Omit this argument to flush the current working directory. Flushing a +directory structure does not flush any files or subdirectories cached from +it. +
+

+ + +

To flush all data from a volume

Issue the fs flushvolume command. +
```
  % fs flushvolume [<dir/file path>⁺]
+
```
+
where +
+
flushv +
Is the shortest acceptable abbreviation of flushvolume. +
dir/file path +
Names a file or directory from each volume to flush from the cache. +The Cache Manager flushes everything in the cache that it has fetched from the +same volume. Omit this argument to flush all cached data fetched from +the volume that contains the current working directory. +
+

+ + +

To force the Cache Manager to notice other volume changes

Issue the fs checkvolumes command. +
```
   % fs checkvolumes
+
```
+
where checkv is the shortest acceptable abbreviation of +checkvolumes. +

The following command confirms that the command completed +successfully: +

   All volumeID/name mappings checked.
+

+ + +

To flush one or more mount points

Issue the fs flushmount command. +
```
   % fs flush [<dir/file path>⁺]
+
```
+
where +
+
flushm +
Is the shortest acceptable abbreviation of flushmount. +
dir/file path +
Names each mount point to flush from the cache. Omit this argument +to flush the current working directory. Files or subdirectories cached +from the associated volume are unaffected. +
+

Maintaining Server Preference Ranks

+ + + + + + +

As mentioned in the introduction to this chapter, AFS uses client-side data +caching and callbacks to reduce the amount of network traffic in your +cell. The Cache Manager also tries to make its use of the network as +efficient as possible by assigning preference ranks to server +machines based on their network proximity to the local machine. The +ranks bias the Cache Manager to fetch information from the server machines +that are on its own subnetwork or network rather than on other networks, if +possible. Reducing the network distance that data travels between +client and server machine tends to reduce network traffic and speed the Cache +Manager's delivery of data to applications. +

The Cache Manager stores two separate sets of preference ranks in kernel +memory. The first set of ranks applies to machines that run the Volume +Location (VL) Server process, hereafter referred to as VL Server +machines. The second set of ranks applies to machines that run +the File Server process, hereafter referred to as file server +machines. This section explains how the Cache Manager sets +default ranks, how to use the fs setserverprefs command to change +the defaults or set new ranks, and how to use the fs getserverprefs +command to display the current set of ranks. +

How the Cache Manager Sets Default Ranks

As the afsd program initializes the Cache Manager, it +assigns a preference rank of 10,000 to each of the VL Server machines listed +in the local /usr/vice/etc/CellServDB file. It then +randomizes the ranks by adding an integer randomly chosen from the range 0 +(zero) to 126. It avoids assigning the same rank to machines in one +cell, but it is possible for machines from different cells to have the same +rank. This does not present a problem in use, because the Cache Manager +compares the ranks of only one cell's database server machines at a +time. Although AFS supports the use of multihomed database server +machines, the Cache Manager only uses the single address listed for each +database server machine in the local /usr/vice/etc/CellServDB +file. Only Ubik can take advantage of a multihomed database server +machine's multiple interfaces. +

The Cache Manager assigns preference ranks to a file server machine when it +obtains the server's VLDB record from the VL Server, the first time that +it accesses a volume that resides on the machine. If the machine is +multihomed, the Cache Manager assigns a distinct rank to each of its +interfaces (up to the number of interfaces that the VLDB can store for each +machine, which is specified in the IBM AFS Release Notes). +The Cache Manager compares the interface's IP address to the local +machine's address and applies the following algorithm: +

If the local machine is a file server machine, the base rank for each of +its interfaces is 5,000. +
If the file server machine interface is on the same subnetwork as the +local machine, its base rank is 20,000. +
If the file server machine interface is on the same network as the local +machine, or is at the distant end of a point-to-point link with the local +machine, its base rank is 30,000. +
If the file server machine interface is on a different network than the +local machine, or the Cache Manager cannot obtain network information about +it, its base rank is 40,000. +

If the client machine has only one interface, the Cache Manager compares it +to the server interface's IP address and sets a rank according to the +algorithm. If the client machine is multihomed, the Cache Manager +compares each of the local interface addresses to the server interface, and +assigns to the server interface the lowest rank that results from comparing it +to all of the client interfaces. +

After assigning a base rank to a file server machine interface, the Cache +Manager adds to it a number randomly chosen from the range 0 (zero) to +15. As an example, a file server machine interface in the same +subnetwork as the local machine receives a base rank of 20,000, but the Cache +Manager records the actual rank as an integer between 20,000 and +20,015. This process reduces the number of interfaces that have exactly +the same rank. As with VL Server machine ranks, it is possible for file +server machine interfaces from foreign cells to have the same rank as +interfaces in the local cell, but this does not present a problem. Only +the relative ranks of the interfaces that house a specific volume are +relevant, and AFS supports storage of a volume in only one cell at a +time. +

How the Cache Manager Uses Preference Ranks

Each preference rank pairs an interface's IP address with an +integer that can range from 1 to 65,534. A lower rank (lower number) +indicates a stronger preference. Once set, a rank persists until the +machine reboots, or until you use the fs setserverprefs command to +change it. +

The Cache Manager uses VL Server machine ranks when it needs to fetch +volume location information from a cell. It compares the ranks for the +cell's VL Server machines and attempts to contact the VL Server process +on the machine with the best (lowest integer) rank. If it cannot reach +that VL Server, it tries to contact the VL Server with the next best rank, and +so on. If all of a cell's VL Server machines are inaccessible, the +Cache Manager cannot fetch data from the cell. +

Similarly, when the Cache Manager needs to fetch data from a volume, it +compares the ranks for the interfaces of machines that house the volume, and +attempts to contact the interface that has the best rank. If it cannot +reach the fileserver process via that interface, it tries to +contact the interface with the next best integer rank, and so on. If it +cannot reach any of the interfaces for machines that house the volume, it +cannot fetch data from the volume. +

Displaying and Setting Preference Ranks

To display the file server machine ranks that the Cache Manager is +using, use the fs getserverprefs command. Include the +-vlservers flag to display VL Server machine ranks instead. +By default, the output appears on the standard output stream (stdout), but you +can write it to a file instead by including the -file +argument. +

The Cache Manager stores IP addresses rather than hostnames in its kernel +list of ranks, but by default the output identifies interfaces by hostname +after calling a translation routine that refers to either the cell's name +service (such as the Domain Name Server) or the local host table. If an +IP address appears in this case, it is because the translation attempt +failed. To bypass the translation step and display IP addresses rather +than hostnames, include the -numeric flag. This can +significantly speed up the output. +

You can use the fs setserverprefs command to reset an existing +preference rank, or to set the initial rank of a file server machine interface +or VL Server machine for which the Cache Manager has no rank. The ranks +you set persist until the machine reboots or until you issue the fs +setserverprefs command again. To make a rank persist across a +reboot, place the appropriate fs setserverprefs command in the +machine's AFS initialization file. +

As with default ranks, the Cache Manager adds a randomly chosen integer to +each rank range that you assign. For file server machine interfaces, +the randomizing number is from the range 0 (zero) to 15; for VL Server +machines, it is from the range 0 (zero) to 126. For example, if you +assign a rank of 15,000 to a file server machine interface, the Cache Manager +stores an integer between 15,000 to 15,015. +

To assign VL Server machine ranks, list them after the -vlserver +argument to the fs setserverprefs command. +

To assign file server machine ranks, use or more of the three possible +methods: +

List them after the -servers argument on the command +line. +
Record them in a file and name it with the -file +argument. You can easily generate a file with the proper format by +including the -file argument to the fs getserverprefs +command. +
Provide them via the standard input stream, by including the +-stdin flag. This enables you to feed in values directly +from a command or script that generates preferences using an algorithm +appropriate for your cell. It must generate them in the proper format, +with one or more spaces between each pair and between the two parts of the +pair. The AFS distribution does not include such a script, so you must +write one if you want to use this method. +

You can combine any of the -servers, -file, and +-stdin options on the same command line if you wish. If more +than one of them specifies a rank for the same interface, the one assigned +with the -servers argument takes precedence. You can also +provide the -vlservers argument on the same command line to set VL +Server machine ranks at the same time as file server machine ranks. +

The fs command interpreter does not verify hostnames or IP +addresses, and so willingly stores ranks for hostnames and addresses that +don't actually exist. The Cache Manager never uses such ranks +unless the same VLDB record for a server machine records the same incorrect +information. + + +

To display server preference ranks

Issue the fs getserverprefs command to display the Cache +Manager's preference ranks for file server machines or VL Server +machines. +
```
   % fs getserverprefs [-file <output to named file>] [-numeric] [-vlservers]
+
```
+
where +
+
gp +
Is an acceptable alias for getserverprefs (gets is +the shortest acceptable abbreviation). +
-file +
Specifies the pathname of the file to which to write the list of +ranks. Omit this argument to display the list on the standard output +stream (stdout). +
-numeric +
Displays the IP address, rather than the hostname, of each ranked machine +interface. Omit this flag to have the addresses translated into +hostnames, which takes longer. +
-vlservers +
Displays ranks for VL Server machines rather than file server +machines. +
+
The following example displays file server machine ranks. The +-numeric flag is not used, so the appearance of an IP address +indicates that is not currently possible to translate it to a hostname. +
+
```
   % fs gp
+   fs5.abc.com         20000
+   fs1.abc.com         30014
+   server1.stateu.edu  40011
+   fs3.abc.com         20001
+   fs4.abc.com         30001
+   192.12.106.120      40002
+   192.12.106.119      40001
+      .   .   .   .   .     . .
+
```
+

+ + + +

To set server preference ranks

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs setserverprefs command to set the Cache +Manager's preference ranks for one or more file server machines or VL +Server machines. +
```
   # fs setserverprefs [-servers <fileserver names and ranks>⁺]  \
+                       [-vlservers <VL server names and ranks>⁺]  \
+                       [-file <input from named file>] [-stdin]
+
```
+
where +
+
sp +
Is an acceptable alias for setserverprefs (sets is +the shortest acceptable abbreviation). +
-servers +
Specifies one or more pairs of file server machine interface and +rank. Identify each interface by its fully-qualified hostname or IP +address in dotted decimal format. Acceptable ranks are the integers +from 1 to 65534. Separate the parts of a pair, +and the pairs from one another, with one or more spaces. +
-vlservers +
Specifies one or more pairs of VL Server machine and rank. Identify +each machine by its fully-qualified hostname or IP address in dotted decimal +format. Acceptable ranks are the integers from 1 to +65534. +
-file +
Specifies the pathname of a file that contains one more pairs of file +server machine interface and rank. Place each pair on its own line in +the file. Use the same format for interfaces and ranks as with the +-servers argument. +
-stdin +
Indicates that pairs of file server machine interface and rank are being +provided via the standard input stream (stdin). The program or script +that generates the pairs must format them in the same manner as for the +-servers argument. +
+

Managing Multihomed Client Machines

+ + + + + + +

The File Server can choose the interface to which to send a message when it +initiates communication with the Cache Manager on a multihomed client machine +(one with more than one network interface and IP address). If that +interface is inaccessible, it automatically switches to an alternate. +This improves AFS performance, because it means that the outage of an +interface does not interrupt communication between File Server and Cache +Manager. +

The File Server can choose the client interface when it sends two types of +messages: +

A message to break the callback that the Cache Manager holds on a cached +file +
A ping message to check that the Cache Manager is still +accessible and responding; the File Server sends such a message every few +minutes +

(The File Server does not choose which client interface to respond to when +filling a Cache Manager's request for AFS data. In that case, it +always responds to the client interface via which the Cache Manager sent the +request.) +

The Cache Manager compiles the list of eligible interfaces on its client +machine automatically as it initializes, and records them in kernel +memory. When the Cache Manager first establishes a connection with the +File Server, it sends along the list of interface addresses. The File +Server records the addresses, and uses the one at the top of the list when it +needs to break a callback or send a ping to the Cache Manager. If that +interface is inaccessible, the File Server simultaneously sends a message to +all of the other interfaces in the list. Whichever interface replies +first is the one to which the File Server sends future messages. +

You can control which addresses the Cache Manager registers with File +Servers by listing them in two files in the /usr/vice/etc directory +on the client machine's local disk: NetInfo and +NetRestrict. If the NetInfo file exists when the +Cache Manager initializes, the Cache Manager uses its contents as the basis +for the list of 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. +

You can also use the fs setclientaddrs command to change the +list of addresses stored in the Cache Manager's kernel memory, without +rebooting the client machine. The list of addresses you provide on the +command line completely replaces the current list in kernel memory. The +changes you make persist only until the client machine reboots, +however. To preserve the revised list across reboots, list the +interfaces in the NetInfo file (and if appropriate, the +NetRestrict file) in the local /usr/vice/etc +directory. (You can also place the appropriate fs +setclientaddrs command in the machine's AFS initialization script, +but that is less efficient: by the time the Cache Manager reads the +command in the script, it has already compiled a list of interfaces.) +

To display the list of addresses that the Cache Manager is currently +registering with File Servers, use the fs getclientaddrs +command. +

Keep the following in mind when you change the NetInfo or +NetRestrict file, or issue the fs getclientaddrs or +fs setclientaddrs commands: +

When you issue the fs setclientaddrs command, the revised list +of addresses does not propagate automatically to File Servers with which the +Cache Manager has already established a connection. They continue to +use the list that the Cache Manager registered with them when it first +established a connection. To force previously contacted File Servers to +use the revised list, you must either reboot each file server machine, or +reboot the client machine after changing its NetInfo file, +NetRestrict file, or both. +
The fs command interpreter verifies that each of the addresses +you specify on the fs setclientaddrs command line is actually +configured with the client machine's operating system. If it is +not, the command fails with an error message that marks the address as a +Nonexistent interface. +
As previously noted, the File Server does not use the registered list of +addresses when it responds to the Cache Manager's request for data (as +opposed to initiating communication itself). It always attempts to send +its reply to the interface from which the Cache Manager sent the +request. If the reply attempt fails, the File Server selects an +alternate route for resending the reply according to its server machine's +network routing configuration, not the list of addresses registered by the +Cache Manager. +
The Cache Manager does not use the list of interfaces when choosing the +interface via which to establish a connection to a File Server. +
The list of addresses that the fs getclientaddrs command +displays is not necessarily the one that a specific File Server is using, if +an administrator has issued the fs setclientaddrs command since the +Cache Manager first contacted that File Server. It determines only +which addresses the Cache Manager registers when connecting to File Servers in +future. +

+ + + + +

To create or edit the client NetInfo file

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Using a text editor, open the /usr/vice/etc/NetInfo +file. Place one IP address in dotted decimal format (for example, +192.12.107.33) on each line. On the +first line, put the address that you want each File Server to use +initially. The order of the remaining machines does not matter, because +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. +
If you want the Cache Manager to start using the revised list immediately, +either reboot the machine, or use the fs setclientaddrs command to +create the same list of addresses in kernel memory directly. +

+ + + + +

To create or edit the client NetRestrict file

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Using a text editor, open the /usr/vice/etc/NetRestrict +file. Place one IP address in dotted decimal format on each +line. The order of the addresses is not significant. Use the +value 255 as a wildcard that represents all possible addresses in +that field. For example, the entry +192.12.105.255 indicates that the Cache +Manager does not register any of the addresses in the 192.12.105 +subnet. +
If you want the Cache Manager to start using the revised list immediately, +either reboot the machine, or use the fs setclientaddrs command to +set a list of addresses that does not included the prohibited ones. +

+ + +

To display the list of addresses from kernel memory

Issue the fs getclientaddrs command. +
```
   % fs getclientaddrs 
+
```
+
where gc is an acceptable alias for getclientaddrs +(getcl is the shortest acceptable abbreviation). +

The output lists each IP address on its own line, in dotted decimal +format. + + +

To set the list of addresses in kernel memory

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs setclientaddrs command to replace the list of +addresses currently in kernel memory with a new list. +
```
   # fs setclientaddrs [-address <client network interfaces>⁺]
+
```
+
where +
+
sc +
Is an acceptable alias for setclientaddrs (setcl is +the shortest acceptable abbreviation). +
-address +
Specifies one or more IP addresses in dotted decimal format (hostnames are +not acceptable). Separate each address with one or more spaces. +
+

Controlling the Display of Warning and Informational Messages

+ + +

By default, the Cache Manager generates two types of warning and +informational messages: +

It sends user messages, which provide user-level status and +warning information, to user screens. +
It sends console messages, which provide system-level status +and warning information, to the client machine's designated +console. +

You can use the fs messages command to control whether the Cache +Manager displays either type of message, both types, or neither. It is +best not to disable messages completely, because they provide useful +information. +

If you want to monitor Cache Manager status and performance more actively, +you can use the afsmonitor program to collect an extensive set of +statistics (it also gathers File Server statistics). If you experience +performance problems, you can use fstrace suite of commands to +gather a low-level trace of Cache Manager operations, which the AFS Support +and Development groups can analyze to help solve your problem. To learn +about both utilities, see Monitoring and Auditing AFS Performance. + + +

To control the display of warning and status messages

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs messages command, using the -show +argument to specify the type of messages to be displayed. +
```
   # fs messages -show <user|console|all|none>
+
```
+
where +
+
me +
Is the shortest acceptable abbreviation of messages. +
-show +
Specifies the types of messages to display. Choose one of the +following values: +
+
user +
Sends user messages to user screens. +
console +
Sends console messages to the console. +
all +
Sends user messages to user screens and console messages to the console +(the default if the -show argument is omitted). +
none +
Disables messages completely. +
+
+

Displaying and Setting the System Type Name

+ + +

The Cache Manager stores the system type name of the local client machine +in kernel memory. It reads in the default value from a hardcoded +definition in the AFS client software. +

The Cache Manager uses the system name as a substitute for the +@sys variable in AFS pathnames. The variable is useful when +creating a symbolic link from the local disk to an AFS directory that houses +binaries for the client machine's system type. Because the +@sys variable automatically steers the Cache Manager to the +appropriate directory, you can create the same symbolic link on client +machines of different system types. (You can even automate the creation +operation by using the package utility described in Configuring Client Machines with the package Program.) The link also remains valid when you upgrade the +machine to a new system type. +

Configuration is simplest if you use the system type names that AFS +assigns. For a list, see the IBM AFS Release Notes. +

To display the system name stored in kernel memory, use the sys +or fs sysname command. To change the name, add the latter +command's -newsys argument. + + + + +

To display the system type name

Issue the fs sysname or sys command. +
```
   % fs sysname 
+   
+   % sys
+
```
+

The output of the fs sysname command has the following +format: +

   Current sysname is 'system_name'
+

The sys command displays the system_name string with no +other text. +

To change the system type name

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs sysname command, using the -newsys +argument to specify the new name. +
```
   # fs sysname <new sysname>
+
```
+
where +
+
sys +
Is the shortest acceptable abbreviation of sysname. +
new sysname +
Specifies the new system type name. +
+

Enabling Asynchronous Writes

+ + + +

By default, the Cache Manager writes all data to the File Server +immediately and synchronously when an application program closes a +file. That is, the close system call does not return until +the Cache Manager has actually written all of the cached data from the file +back to the File Server. You can enable the Cache Manager to write +files asynchronously by specifying the number of kilobytes of a file that can +remain to be written to the File Server when the Cache Manager returns control +to the application. +

Enabling asynchronous writes can be helpful to users who commonly work with +very large files, because it usually means that the application appears to +perform faster. However, it introduces some complications. It is +best not to enable asynchronous writes unless the machine's users are +sophisticated enough to understand the potential problems and how to avoid +them. The complications include the following: +

In most cases, the Cache Manager returns control to applications earlier +than it does by default, but it is not guaranteed to do so. Users +cannot always expect faster performance. +
If an asynchronous write fails, there is no way to notify the application, +because the close system call has already returned with a code +indicating success. +
Asynchronous writing increases the possibility that the user fails to +notice when a write operation makes a volume exceed its quota. As +always, the portion of the file that exceeds the quota is lost, as indicated +by a message like the following: +
```
   No space left on device
+
```
+
To avoid losing data because of insufficient quota, before closing a file +users must verify that the volume housing the file has enough free space to +accommodate it. +

When you enable asynchronous writes by issuing the fs +storebehind command, you set the number of kilobytes of a file that can +still remain to be written to the File Server when the Cache Manager returns +control to the application program. You can apply the setting either to +all files manipulated by applications running on the machine, or only to +certain files: +

The setting that applies to all files is called the default store +asynchrony for the machine, and persists until the machine +reboots. If, for example, you set the default store asynchrony to 10 +KB, it means that when an application closes a file, the Cache Manager can +return control to the application as soon as no more than 10 KB of a file that +the application has closed remain to be written to the File Server. +
The setting for an individual file overrides the default store asynchrony +and persists as long as there is an entry for the file in the internal table +that the Cache Manager uses to track information about files. In +general, such an entry persists at least until an application closes the file +or exits completely, but the Cache Manager is free to recycle the entry if the +file is inactive and it needs to free up slots in the table. To be sure +the entry exists in the table, issue the fs storebehind command +shortly before closing the file. +

+ + +

To set the default store asynchrony

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs storebehind command with the -allfiles +argument. +
```
   # fs storebehind -allfiles  <new default (KB)> [-verbose]
+
```
+
where +
+
st +
Is the shortest acceptable abbreviation of storebehind. +
-allfiles +
Sets the number of kilobytes of data that can remain to be written to the +File Server when the Cache Manager returns control to the application that +closed a file. +
-verbose +
Produces a message that confirms the new setting. +
+

+ + +

To set the store asynchrony for one or more files

Verify that you have the w (write) permission on the +access control list (ACL) of each file for which you are setting the store +asynchrony, by issuing the fs listacl command, which is described +fully in Displaying ACLs. +
```
   % fs listacl dir/file path
+
```
+
Alternatively, become the local superuser root on the client +machine, if you are not already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs storebehind command with the -kbytes +and -files arguments. +
```
   # fs storebehind -kbytes <asynchrony for specified names> \
+                    -files <specific pathnames>⁺  \
+                    [-verbose]
+
```
+
where +
+
st +
Is the shortest acceptable abbreviation of storebehind. +
-kbytes +
Sets the number of kilobytes of data that can remain to be written to the +File Server when the Cache Manager returns control to the application that +closed a file named by the -files argument. +
-files +
Specifies each file for which to set a store asynchrony that overrides the +default. Partial pathnames are interpreted relative to the current +working directory. +
-verbose +
Produces a message that confirms that new setting. +
+

+ + +

To display the default store asynchrony

Issue the fs storebehind command with no arguments, or with the +-verbose flag only. +
```
   % fs storebehind  [-verbose]
+
```
+
where +
+
st +
Is the shortest acceptable abbreviation of storebehind. +
-verbose +
Produces output that reports the default store asynchrony. +
+

+ + +

To display the store asynchrony for one or more files

Issue the fs storebehind command with the -files +argument only. +
```
   % fs storebehind -files <specific pathnames>⁺ 
+
```
+
where +
+
st +
Is the shortest acceptable abbreviation of storebehind. +
-files +
Specifies each file for which to display the store asynchrony. +Partial pathnames are interpreted relative to the current working +directory. +
+

The output lists each file separately. If a value has previously +been set for the specified files, the output reports the following: +

   Will store up to y kbytes of file asynchronously.
+   Default store asynchrony is x kbytes.
+

If the default store asynchrony applies to a file (because you have not set +a -kbytes value for it), the output reports the following: +

   Will store file according to default.
+   Default store asynchrony is x kbytes.
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd016.htm b/doc/html/AdminGuide/auagd016.htm new file mode 100644 index 0000000..044b3f4 --- /dev/null +++ b/doc/html/AdminGuide/auagd016.htm @@ -0,0 +1,1148 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Configuring Client Machines with the package Program

The package program automates many aspects of the +client configuration process. With the package program, you +can easily configure the local disk of numerous clients by defining global +configuration files. + + + + +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands or instructions in a prototype file: +
+ + + + + + + + +
Configure a client machine's local disk + package +
Define directory + D [update_code] directory owner +group mode_bits +
Define file + F [update_code] file source_file +[owner group mode_bits] +
Define symbolic link + L [update_code] link actual_file +[owner group mode_bits] +
Define block special device + B device_name major_device_number +minor_device_number owner group mode_bits +
Define character special device + C device_name major_device_number +minor_device_number owner group mode_bits +
Define socket + S socket_name [owner group +mode_bits] +
+

Using the package Program

+ + +

The package program uses system-independent prototype +files to define a standard disk configuration; a prototype file +indicates which files reside on the local client disk, which files are links +into AFS, etc. The prototype files are then compiled into +configuration files for each different system type. +

Not all client machines have the same configuration. If desired, you +can create different prototype files for different client functions (print +server, regular client, etc.). +

The package program compares the contents of a local client disk +with the configuration file. If there are any differences, the +package program makes the necessary updates to the local disk by +copying the files from AFS onto the disk. The package +program can also be configured to delete files that are not part of the system +configuration or automatically reboot the client when certain files (such as +the dkload file) have been updated. +

The package program does require that you take some time to +prepare the prototype files, but it provides the following benefits: +

You no longer need to configure each machine individually; the +prototype configuration file applies to all machines. +
You can change the configuration of machines simply by changing the +prototype file and rebooting the clients. +
Disk organization is uniform across a set of machines. +
The configuration files serve as a record of files on the disk and +symbolic links into AFS. +

Using Package on File Server Machines

While the package program was designed for use on client +machines, it can also be used to configure a file server machine's +disk. However, if any of the files referred to in a configuration file +reside in volumes on the file server, the package program cannot +access the volumes during reboot (and until the File Server process and Volume +Server process start up again). +

Since the package program aborts when it cannot access a file, +you need to eliminate references to files in AFS that reside in volumes on the +file server machine. Because of these constraints, the remainder of +this chapter assumes the package program is being used for client +configurations. +

Package Overview

There are three main steps to follow before running the +package program: +

Preparing function-specific prototype files (and any included +library files). +
Modifying the package Makefile and compiling +prototype files into system-specific configuration files. +
Modifying client machines to run the appropriate package +configuration file automatically. +

The following sections summarize these steps. +

Preparing Prototype Files

+ + +

Begin by listing the different functions or roles client machines perform +and the local disk configurations that support those functions. Example +roles include a standard client that provides AFS access, a print server that +drives a printer, and a backup machine on which you issue commands from the +backup suite. Create a different prototype file +for each role. +

A prototype file defines the disk configuration that supports a specific +role. Usually, prototype files are function-specific, but system +independent; system-specific values can be defined using variables and +library files. Then, when you modify a variable or library file, the +change gets propagated to all appropriate clients when the package +program is invoked. +

Methods for building flexible prototype files that are easy to maintain are +presented in Example Prototype and Library Files. +

Compiling Prototype Files

+ + + +

Prototype files are usually system-independent, but can include +ifdef statements to satisfy the needs of different system +types. The prototype files are compiled to generate operating-system +specific versions. During compilation, the package program +selects the definitions suitable for each system type and replaces any +variables with actual values. These compiled, machine-specific files +are called configuration files. +

Prototype files are compiled using a standard-type Makefile +file, as described in The Package Makefile File. +

Preparing Clients

Once system-specific configuration files exist, the package +program is ready to run on the clients. You must first make the +package binary available and specify the correct configuration +file. +

Modify the clients as described below: +

Create a .package file in the root ( / ) +directory of each client's local disk that defines the default +configuration file. +
Make the package binary (/etc/package) available on +the local disk. +
Modify the machine's initialization file (/etc/rc or +equivalent) to include a call to the package program. +

These steps are discussed more completely in Modifying Client Machines. +

The package Directory Structure

+ +

This section assumes that the package-related files have been +installed in three subdirectories of the +/afs/cellname/wsadmin directory: +src, lib and etc, as recommended in the +IBM AFS Quick Beginnings. +

These directories contain several sample prototype, library, and +configuration files, which can help to clarify how the package +program works. However, they are not necessarily suitable for use in +your cell; you must modify them for your needs. +

The src directory

The src directory contains some sample prototype +files (used to build the configuration files), the Makefile file +used to build them, and the resulting compiled configuration files. +

Prototype files have names of the form +function.proto. For example, a +minimal.proto file defines the minimum set of library files +need to run AFS and astaff.dkload.proto file defines +a client configuration that uses the a dynamic kernel loading program. +Prototype files can also contain definitions for system administrative files, +such as a hosts.equiv file. +

The Makefile file is used to compile the system-independent +prototype files into system-specific configuration files. To learn how +to modify this file for use in your cell, see The Package Makefile File. +

Configuration files are the compiled version of the prototype files and are +named function.sysname. +Configuration files also appear in the etc subdirectory, which the +package program accesses when configuring disks. +

The lib directory

The lib directory contains many of the example library files +referred to in prototype files. For example, the +base.generic file is a system-independent file which +includes a definition of the cell name, system options, and variables; +these are used to set the owner, group, and +mode_bits fields in the file and the symbolic link +definitions. +

The etc directory

The etc directory contains the system-specific configuration +files built from the prototype files in the src +subdirectory. The package program uses the configuration +files in the etc directory to configure disks. +

Some of the example files include minimal and staff +prototype files compiled for different system types. +

Example Prototype and Library Files

+ + +

A prototype file is a template that defines the configuration of a +client's local disk. Prototype files are usually function-specific +(for example, a backup machine, print server, etc.) but +system-independent. Prototype files support the use of ifdef +statements and variables, so you can include system-specific +definitions. The actual system-specific configuration file is generated +when the prototype file is compiled. +

The components defined in a prototype file can include the directories, +files, symbolic links, block special devices, character special devices and +sockets that need to reside on a client's local disk in order for it to +perform a specific role, such as a print server or backup machine. +Thus, we recommend that you construct a unique prototype file for each +different client function. +

To make the package program more effective and easy to maintain, +create prototype files that are modular and generic, instead of specific, by +using library files and variables: + + +

By creating general-purpose library files, you can include the same +library file in many prototype files. Thus, you can make global +configuration changes by modifying a single library file; you do not need +to modify each prototype file. +
Variables enable you to change definitions simply by changing the +variable's value. +

An Example Prototype File

+ +

The following is part of an example prototype file that contains the +minimum definitions necessary to run AFS. A similar file called +minimal.proto can reside in your src +subdirectory. As recommended, this prototype file references library +files and does not include actual definitions. +

            .
+            .
+   # Package prototype for a minimal configuration.
+   # Base components
+   %include ${wsadmin}/lib/base.generic
+   # Machine-specific components
+   %ifdef rs_aix42
+   %include ${wsadmin}/lib/rs_aix42.readonly
+   %include ${wsadmin}/lib/rs_aix42.AFS
+   %endif rs_aix42
+   %ifdef alpha_dux40
+   %include ${wsadmin}/lib/alpha_dux40.readonly
+   %include ${wsadmin}/lib/alpha_dux40.AFS
+   %endif alpha_dux40
+   %ifdef sun4x_56
+   %include ${wsadmin}/lib/sun4x_56.readonly
+   %include ${wsadmin}/lib/sun4x_56.AFS
+   %endif sun4x_56
+            .
+            .
+

In the previous example, the first uncommented line includes the +/lib/base.generic library file. This library file can +contain definitions appropriate for many prototype files; the +base.generic library file can also be included in other +prototype files, like a staff.proto or +backup.proto file. An example library file appears in +the following section. +

Note that system-specific definitions are permitted through the use of +ifdef statements and variables (for example, ${wsadmin} +is used to specify pathnames). Thus, the same prototype file can be +used to configure a machine running AIX 4.2 or Solaris 2.6, even +though they require different files, directories, symbolic links and +devices. +

In the next uncommented lines of this example, the administrator has +constructed different library files for different system types. Each of +these is compiled into unique configuration files. For instance, the +following lines in this prototype file tell the package program to +use the library files lib/rs_aix42.readonly and +lib/rs_aix42.AFS for the configuration file when the value +rs_aix42 has been declared. (The system-type definition is +declared in the Makefile; see The Package Makefile File.) +

   %ifdef rs_aix42
+   %include ${wsadmin}/lib/rs_aix42.readonly
+   %include ${wsadmin}/lib/rs_aix42.AFS
+   %endif rs_aix42
+

Similarly, the following lines tell the package program to use +the library files lib/sun4x_56.readonly and +lib/sun4x_56.AFS when the value sun4x_56 has been +declared. +

   %ifdef sun4x_56
+   %include ${wsadmin}/lib/sun4x_56.readonly
+   %include ${wsadmin}/lib/sun4x_56.AFS
+   %endif sun4x_56
+

Example Library File

+ + + + +

The following is part of an example library file for basic configuration +definitions. A similar file, called base.generic, can +reside in your lib subdirectory. Note that configurations +are defined using standard ifdef statements. +

            .
+            .
+   #
+   # Base package definitions.
+   #
+   %ifndef	cell
+   %define	cell	abc.com
+   %endif	cell
+   %ifndef	sys
+   %include /etc/package.sys
+   %endif	sys
+   %define	${name}		${name}
+   %define	${cpu}		${cpu}
+   %define	${sys}		${sys}
+   %define	${dept}		${dept}
+   %define	${hostname}	${hostname}
+   %ifdef	rs_aix42
+   %	define 	AIX
+   %	define	rootlinks
+   %ifndef	noafsd 
+   %	define	afsd
+   %endif	noafsd
+   %endif	rs_aix42
+            .
+            .
+   #
+   # Some definitions to handle common combinations of owner, group,
+   # and protection fields.
+   #
+   %define	rzmode		root wheel 600
+   %define	usermode	root wheel 666
+   %define      systemmode	root wheel 644
+   %define	diskmode	root wheel 644
+   %define	ptymode		root wheel 666
+   %define	ttymode		root wheel 666
+            .
+            .
+   %define aix_rootbin	   root bin
+   %define aix_rootprintq  root printq
+   %define aix_rootstaff   root staff
+   %define aix_rootsys	   root system
+   %define aix_binbin      bin bin
+   %define aix_binmail	   bin mail
+   %define aix_binsys	   bin system
+   %define aix_addsys	   adduser system
+   %define aix_romode	   444
+   %define aix_loginmode   544
+   %define aix_usermode	   666
+   %define aix_systemmode  644
+   %define aix_textmode	   644
+   %define aix_rwmode1	   660
+   %define aix_allrugw	   664
+

The following example library file uses package-specific syntax +to define files, directories, sockets, etc. Each line, called a +configuration file instruction, defines a specific component of +disk configuration. The proper syntax for these instructions is briefly +described in Package Configuration File Instruction Syntax; see the reference page for the package +configuration file in the IBM AFS Administration Reference for +detailed descriptions. +

In this example, the library file contains instructions specific to the +configuration of an rs_aix42 machine. You can have similar +library files in your lib subdirectory. +

            .
+            .
+   #
+   # Generic configuration for an AFS rs_aix42 machine.
+   #
+   D	/                                       ${treemode}
+   D	/afs
+   FAQ	/unix	       ${machine}/unix.std 	${binmode}
+   LA	/unix.std	/unix
+   D	/bin					${treemode}
+   F	/bin/as		${machine}		${binmode}
+   F	/bin/ld		${machine}		${binmode}
+   F	/bin/nm		${machine}		${binmode}
+   FO	/bin/login	${afstest}		${suidmode}
+            .
+            .
+   FAQ  /usr/vice/etc/ThisCell  ${common}/etc/ThisCell ${textmode}
+   FQ	/usr/vice/etc/afsd      ${afstest}/root.client ${binmode}
+   FA	/usr/vice/etc/bos       ${afstest}/bin/bos     ${binmode}
+   FA	/usr/vice/etc/fs        ${afstest}/bin/fs      ${binmode}
+

Package Configuration File Instruction Syntax

+ + +

Within a library file, configuration file instructions are used to define +the specific disk configuration. Each instruction can be used to define +a file, directory, socket, or device on the client machine. The syntax +for each valid instruction type is described briefly here; detailed +descriptions of the fields appear in the AFS Command Reference +Manual. +

D defines a directory +
F defines a file +
L defines a link +
B defines a block special device +
C defines a character special device +
S defines a socket +

Note:

Each configuration instruction must appear on a single, unbroken line. +Instructions sometimes appear here on multiple lines only for +legibility. +

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. +

Local Files versus Symbolic Links

You can take advantage of the AFS by keeping the number of +files on the local client disk to a minimum; instead, create symbolic +links that point into AFS. This can improve machine performance by +allowing more space for caching and swapping. +

Some files, however, must reside on the local disk, as described +below. Create these files in the prototype or library files using the +F (file) instruction, not the L (symbolic link) +instruction. +

The following types of files must reside on the local disk of all AFS +clients: +

Boot sequence files executed before the afsd program +runs. +
Until afsd runs and initializes the Cache Manager, AFS is +inaccessible from the client. Any files that are executed before the +afsd program runs must reside on the local client disk. +
For example, on a machine that uses a disk cache, the +/usr/vice/cache directory must exist when you bring up the Cache +Manager, so that there is a location to create cache files. The binary +files /etc/mount and /etc/umount must be available on +the local disk as the machine boots in order to mount the +/usr/vice/cache directory. +
In addition, certain UNIX files, such as initialization files +(/etc/rc or equivalent) and file system mapping files +(/etc/fstab or equivalent), must reside on the local disk. +
Diagnostic and recovery files +
Certain commands can be used to diagnose and recover from problems caused +by a file server outage. It is best to keep copies of the binaries for +these commands on the local disk. For example, store the bos +and fs binaries in the /usr/vice/etc directory on the +local disk, as well as in the /usr/afsws directory (which in the +conventional configuration is a symbolic link into AFS). Then, set PATH +variables so that the /usr/afsws directory appears before the +/usr/vice/etc directory. Thus, even if users cannot access +AFS (for example, due to a file server outage) they can still access copies of +the bos and fs binaries in the /usr/vice/etc +directory on the local disk. +
Files in the /usr/vice directory +
The contents of the /usr/vice directory, including the cache +files in the cache subdirectory and the configuration files in the +etc subdirectory, must reside on the local disk. For a +description of the files in the directory, see Configuration and Cache-Related Files on the Local Disk. +

+ + + + +

Defining a Directory

The D instruction defines a directory to be +created 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. +

Use the following instruction to define a directory: +

   D[update_code]   directory   owner   group   mode_bits
+

The following example defines the /usr directory: +

   D /usr root wheel 755
+

+ + + + +

Defining a File

The F instruction defines a file to be created on +the local disk. The source file can reside in either AFS or the local +disk. +

If a file of this name already exists, then it is updated with (overwritten +by) the source file, unless the I update code is specified. +If a symbolic link or directory of this name exists, the package +program replaces it with the source file. +
Note: Some files must reside on the local disk; they cannot be symbolic +links. See Local Files versus Symbolic Links. +
+

Use the following instruction to define a file: +

   F[update_code]   file   source_file  [owner   group   mode_bits]
+

An example which creates/updates the file /bin/grep on the local +disk, using /afs/abc.com/rs_aix42/bin/grep as the +source: +

   F /bin/grep /afs/abc.com/rs_aix42 root wheel 755
+

In the following example, two update codes are used, and the +owner, group and mode_bits slots are left +empty, so that the disk file adopts the source file's values for those +slots. +

   FAQ /usr/vice/etc/ThisCell /afs/abc.com/common/etc/ThisCell
+

+ + + + +

Defining a Symbolic Link

The L instruction defines a symbolic link to be +created on the local disk. The symbolic link can point to the AFS file +system or the local disk. If the identical symbolic link already +exists, the package program does nothing. However, if an +element of the same name exists on the disk as a file or directory, the +package program replaces the element with a symbolic link. +
Note: Some files must reside on the local disk; they cannot be symbolic +links. See Local Files versus Symbolic Links. +
+

Use the following instruction to define a symbolic link: +

   L[update_code]  link actual_file  [owner   group   mode_bits]
+

Note:

Do not create a symbolic link to a file whose name begins with the number +sign (#) or percent sign (%). The Cache Manager +interprets such a link as a mount point to a regular or Read/Write volume, +respectively. +

The following example creates a symbolic link from the /etc/ftpd +directory on the local disk to the +/afs/abc.com/hp_ux110/etc/ftpd file in AFS. Since the +owner, group and mode_bits fields are empty, +the symbolic link adopts values for those fields from the actual file: +

   L /etc/ftpd /afs/abc.com/hp_ux110 
+

This example uses the A update code: +

   LA /etc/printcap /afs/abc.com/common/etc/printcap.remote 
+               root wheel 644
+

+ + + + +

Defining a Block Special Device

The B instruction defines a block special device, +which is a device that handles data in units of multibyte blocks, such as a +disk. If a device of the same name already exists, the +package program replaces it with the specified block device. +

Use the following instruction to define a block special device (it appears +on two lines here only for legibility): +

   B device_name   major_device_number   minor_device_number  \
+      owner   group   mode_bits
+

The following example defines a disk called /dev/hd0a to have +major and minor device numbers 1 and 0: +

   B /dev/hd0a 1 0 root wheel 644
+

+ + + + +

Defining a Character Special Device

The C instruction defines a character special +device, which is device that handles data in units of a single character at a +time, such as a terminal or tty. If a device of the same name already +exists, the package program replaces it with the specified +character device. +

Use the following instruction to define a character special device (it +appears here on two lines only for legibility): +

   C device_name   major_device_number   minor_device_number  \
+      owner   group   mode_bits
+

The following example defines the tty called /dev/ttyp5 with +major and minor device numbers 6 and 5: +

   C /dev/ttyp5 6 5 root wheel 666
+

+ + + + +

Defining a Socket

The S instruction defines a socket, which is +communications device for UDP and TCP/IP connections. If a socket of +the same name already exists, the package program replaces +it. +

Use the following instruction to define a socket: +

   S   socket_name   [owner   group   mode_bits]
+

The following example defines a socket called +/dev/printer: +

   S /dev/printer root wheel 777
+

Constructing Prototype and Library Files

+ + + +

This section describes the general steps required to create +package prototype and library files. Refer to the previous +sections for guidelines, and the files in your wsadmin directory +for examples. The construction of prototype and library files is +different for each cell. +

To construct a prototype file and its component library files

Determine where the three package-related subdirectories +(src, lib and etc) reside in your cell's +file tree; the following instructions assume they were loaded into the +/afs/cellname/wsadmin directory, as described +in the IBM AFS Quick Beginnings. +
Decide how many different functions you want client machines in your cell +to perform. We recommend that you construct a separate prototype file +for each function. Common functions include: +
- Standard workstation: provides users with access to files in AFS +
- Printer server: drives a printer; can be combined with "staff" +functionality +
- Backup machine: performs backups of AFS volumes to tape by running +the AFS Backup System software +
+
Determine the minimum functionality needed for all clients (such as AFS +setup) and place these generic definitions in one or more library +files. +
For each type of client (printer server, backup machine, and so on), place +all system-independent definitions in one file, and all operating-system +dependent definitions in another file. +

The Package Makefile File

+ + + +

Once you have created the appropriate prototype and library files, you must +compile the prototype for each system type. The result is a +system-specific configuration file. +

The Makefile file defines the prototype and library files used +and the order of compilation. We recommend that you create your +Makefile file by modifying the example provided with the AFS +distribution, as described in this section. In the conventional +configuration, it is located at +/afs/cellname/wsadmin/src/Makefile. +

Overview

The following list summarizes the sections in the package +Makefile file, identifying each by the header name that begins the +section. More detailed descriptions follow. +

CONFIG= +: Lists all of the configuration files to be created and defines which +prototype files are compiled for which system types. See The CONFIG Section. +
BASE_LIBS= +: Lists the pathnames of all operating-system- and function independent +library files included in any prototype files. See The BASE_LIBS Section. +
MACHINE_LIBS= +: Lists the pathnames of all operating-system-specific library files +included in any prototype files. See The MACHINE_LIBS Section. +
LIBS= +: A one-line instruction that defines LIBS as the combination of +BASE_LIBS and MACHINE_LIBS. See The LIBS Section. +
.SUFFIXES +: Defines all of the suffixes that can appear on a prototype or +configuration file. See The .SUFFIXES Section. +

Finally, the Makefile file contains a set of instructions that +the package program follows to generate configuration files. +It is not generally necessary to alter this section. See The Makefile Instructions Section. +

The CONFIG Section

As mentioned, a configuration file is a prototype file that +has been compiled for a specific operating system type. The +CONFIG section of the Makefile file defines the +prototype files to compile for each system type. The resulting compiled +file is a system-specific configuration file. +

Study the following example taken from the sample Makefile +file. Configuration files are defined by specifying the +prototype-system combination as +prototype_file.sysname. Note that +it is not necessary to generate a configuration file for each prototype-system +type combination. +

   #Makefile...
+   #	(C) Copyright IBM Corporation 1999
+   #	Licensed Materials - Property of IBM
+   #	All Rights Reserved.
+   #
+   CONFIG = \
+            staff.rs_aix42 \
+            staff.alpha_dux40 \
+            staff.xdm.alpha_dux40 \
+            staff.sun4x_56 \
+            staff.hp_ux110 \
+            minimal.rs_aix42 \
+            minimal.alpha_dux40 \
+            minimal.hp_ux110 \
+            minimal.sun4x_56
+

An entry in the CONFIG section has the following format: +

The first part of the entry defines the prototype file and is the same as +the prototype file name (without the .proto +extension). The second part of the entry indicates the system type for +which the prototype file is to be compiled. A complete list of these +suffixes is in the .SUFFIXES section of the +Makefile file, as described in The .SUFFIXES Section. This +prototype_file.sysname definition becomes +the name of the compiled configuration file. +
For example, staff.rs_aix42 indicates that the +staff.proto file is compiled for machines running AIX +4.2. The resulting compiled configuration file is called +staff.rs_aix42. +
Each configuration file must appear on a separate line. +
A backslash must follow the CONFIG= header and every name but +the last one. A backslash must also appear on blank lines. +

The BASE_LIBS Section

This section defines the complete pathname of all system- +and function-independent library files included in any prototype file. +(System-specific library files are defined in the MACHINE_LIBS +section). The pathnames can include the ${wsadmin} variable, +whose value is supplied on the make command line. +

You must include all of the library files referred to in your prototype +files; files included but not used are ignored. +

Study the following example. Note that the all entries (except the +last one) must be followed by a backslash. +

   BASE_LIBS = \
+	   ${wsadmin}/src/admin \
+	   ${wsadmin}/lib/devel \
+	   ${wsadmin}/lib/base.generic
+

The MACHINE_LIBS Section

This section lists the complete pathname of all +operating-system-specific library files included in prototype files. +(System- and function-independent library files are defined in the +BASE_LIBS section.) +

Study the following example. Note that in this example, library +files were grouped by operating-system type. Again, all lines (except +the last one) must be followed by a backslash, the ${wsadmin} +variable is allowed, and files included but not used are ignored. +

   MACHINE_LIBS = \
+           ${wsadmin}/lib/rs_aix42.generic \
+           ${wsadmin}/lib/rs_aix42.generic.dev \
+           ${wsadmin}/lib/rs_aix42.readonly \
+           ${wsadmin}/lib/rs_aix42.readwrite \
+           ${wsadmin}/lib/rt_aix42.generic.printer \
+    \
+    .
+    .
+           ${wsadmin}/lib/alpha_dux40.AFS \
+           ${wsadmin}/lib/hp_ux110.AFS \
+           ${wsadmin}/lib/sun4x_56.AFS \
+           ${wsadmin}/lib/rs_aix42.AFS
+

The LIBS Section

This section contains only one instruction, which indicates +that LIBS is defined as the combination of MACHINE_LIBS +and BASE_LIBS. Insert a blank line after the line to +separate this section from the next. +

   LIBS = ${MACHINE_LIBS} ${BASE_LIBS}
+

The .SUFFIXES Section

This section lists the valid machine-type suffixes. +This list includes system types currently supported for AFS. Unused +suffixes are ignored. +

   .SUFFIXES: .rs_aix42 \
+              .alpha_dux40 \
+              .proto \
+              .sun4x_56 \
+              .i386_linux22 \
+              .hp_ux110
+

The Makefile Instructions Section

The remainder of the Makefile file controls how +the package program generates configuration files. +

Study the following instructions; it is assumed that you are familiar +with programming and Makefile concepts. +

   #The following appear on a single line each in the actual file
+   .proto.rs_aix42: ;  mpp -Dwsadmin=${wsadmin} -Dsys=rs_aix42  
+                           -Dname=$* $*.proto > $@
+   .proto.alpha_dux40: ; mpp -Dwsadmin=${wsadmin} -Dsys=alpha_dux40 
+                           -Dname=$* $*.proto > $@
+   .proto.sun4x_56:  ; mpp -Dwsadmin=${wsadmin} -Dsys=sun4x_56 
+                           -Dname=$* $*.proto > $@
+   .proto.hp_ux110:  ; mpp -Dwsadmin=${wsadmin} -Dsys=hp_ux110  
+                           -Dname=$* $*.proto > $@
+   all: ${CONFIG}
+   ${CONFIG}: ${LIBS}
+   system: install
+   install: ${CONFIG}
+	   cp ${CONFIG} ${wsadmin}/etc
+   clean:
+	   rm -f ${CONFIG} *.BAK *.CKP
+

Modifying the Makefile

+ + + +

Modify the package Makefile files when you +

Add a new prototype file +(function.proto). +
Add a new system type. +
Add new library files. +

The following sections provide brief examples of how to modify the +Makefile file for these reasons. +

Adding a New Prototype File

When you create a new prototype file, add the file name and each system +type for which it is to be built into the CONFIG section of the +Makefile file. +

For example, to add a function.proto file for +alpha_dux40 and hp_ux110, add the following entries to +the CONFIG section: +

   CONFIG = \
+   ...
+           function.alpha_dux40 \
+           function.hp_ux110 \
+   ...
+

If you have added new library files for this prototype function, add those +to the MACHINE_LIBS section. +

Adding a New System Type

For each prototype file that you want to build for the new system type, +add an entry to the CONFIG section. Also add any new +libraries to the MACHINE_LIBS section, and the new system type to +the .SUFFIXES section. +

The following example shows the modifications appropriate when building the +staff and minimal prototype files for this new system +type. +

   CONFIG = \
+   ...
+           staff.sysname \
+           minimal.sysname \
+   ...
+

If you have created corresponding library files for this new machine type, +add them to the MACHINE_LIBS section. +

   MACHINE_LIBS = \
+   ...
+           ${wsadmin}/lib/sysname.generic \
+           ${wsadmin}/lib/sysname.generic.dev \
+           ${wsadmin}/lib/sysname.readonly \
+           ${wsadmin}/lib/sysname.readwrite \
+   ...
+

Add the new system type to the SUFFIXES section. +

   .SUFFIXES: ...\
+            .sysname \
+   ...
+

Add a line to build the configuration files for this system in the section +with the rest of the commands to build configuration files: +

   .proto.sysname: ; mpp -Dwsadmin=${wsadmin} \
+   -Dsys=sysname  -Dname=$* $*.proto > $
+

Adding New Library Files

If you added a new library file for each system type, +sysname.library_file, add these files to +the MACHINE_LIBS section of the Makefile. +

   MACHINE_LIBS = \
+   ...
+           ${wsadmin}/lib/rs_aix42.library_file \
+   ...
+           ${wsadmin}/lib/alpha_dux40.library_file \
+   ...
+           ${wsadmin}/lib/sun4x_56.library_file \
+   ...
+

If you added a new library file that is common to all system types, +library_file, add this only to the BASE_LIBS +section: +

   BASE_LIBS = \
+   ...
+           ${wsadmin}/lib/library_file \
+   ...
+

Compiling Prototype Files

+ + +

The package program generates configuration files and installs +them in the etc and src subdirectories of the directory +designated as wsadmin= on the make command line. +Recompile whenever you modify a prototype or library file. +

To compile prototype files

Note:

These instructions assume that you store your package-related +files in the /afs/cellname/wsadmin +directory. If you use a different directory, substitute its name for +/afs/cellname/wsadmin. +

Verify that you have all privileges in the +/afs/cellname/wsadmin directory and in its +src, lib and etc subdirectories. If +necessary, issue the fs listacl command. +
```
   % fs listacl [dir/file path]
+
```
+
Change to the /afs/cellname/wsadmin/src +subdirectory. +
```
   % cd /afs/cellname/wsadmin/src
+
```
+
Create a backup copy of the Makefile file included in the AFS +distribution. +
```
   % cp  Makefile Makefile.example 
+
```
+
Modify the CONFIG, BASE_LIBS and +MACHINE_LIBS sections of the Makefile file, as described +in The CONFIG Section, The BASE_LIBS Section, and The MACHINE_LIBS Section. +
Compile the prototype files using the make command. +
Use the wsadmin= argument to specify the package +directory. This becomes the value of the ${wsadmin} variable +in the prototype and the library files. +
The package program generates configuration files and installs +them in the etc and src subdirectories of the directory +designated as wsadmin=. +
```
   % make system wsadmin=/afs/cellname/wsadmin
+
```
+

Modifying Client Machines

+ + + + +

To prepare a client to run the package program automatically, +perform the following steps. The instructions are generic because they +do not refer to system-specific configuration files. If desired, you +can invoke the package program with specific arguments, as +described in the IBM AFS Administration Reference. +

Specify the configuration file to use. +
The .package file in the client machine's root ( +/) directory is redirected as an argument to the package +command; the .package file specifies which +configuration file the package program uses. +
Make the package binary available to the client, either by +copying it to the local disk, or by creating a symbolic link to AFS. +
- A symbolic link saves local disk space. However, when the file +server machine that houses it is down, the package binary is +inaccessible. +
- Keeping the package binary on the local disk enables you to run +the package program even if file server is down. However, a +file server machine outage usually makes it difficult to run the +package program because most configuration file instructions refer +to files in AFS. A local copy of the package binary can be +useful if the files referred to in instructions are in replicated +volumes. +
+
Modify the client machine's initialization file to invoke the +package program at reboot. The client machine reboots a +second time if the package program updates any files marked with +the Q update code. +

To prepare a client machine to run the package program

Repeat these instructions on every client that runs the +package program. +

These instructions assume that the package configuration files +(created when the prototype files were compiled) reside in the +/afs/cellname/wsadmin/etc directory . +

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Create the .package file in the root ( /) +directory and specify the name of the prototype file to use. Do not +include the system-type suffix (such as .rs_aix42); the +package program automatically determines the correct machine +type. +
```
   # echo "/afs/cellname/wsadmin/etc/config_file" >> /.package
+
```
+
For example, to configure a machine for a member of staff machine (assuming +the proper prototype file had been defined and compiled for the system type), +the appropriate command is: +
```
   # echo "/afs/cellname/wsadmin/etc/staff" >> /.package
+
```
+
Make the package binary available on the local disk as +/etc/package. Issue one of the following commands, depending +on whether you want to create a file or create a symbolic link. +
To store the package binary locally, enter the following +command: +
```
   # cp /afs/cellname/sysname/usr/afsws/etc/package   /etc/package
+
```
+
To create a symbolic link, enter the following command: +
```
   # ln -s /afs/cellname/sysname/usr/afsws/etc/package   /etc/package
+
```
+

Add the following lines to the appropriate initialization file, after the +afsd command is invoked. If this is a file server machine, +the bosserver command must follow the package +command. +

Using the -v and -c options is recommended. +The -v flag produces a detailed trace, and the -c option +appends the system type to the base name of the configuration file. See +the IBM AFS Administration Reference for a description of other +options. +
Note: Replace the shutdown command with a similar command if it is not +appropriate for rebooting your machine. +
+

   if [ -f /etc/package ]; then
+           if [ -f /.package ]: then
+                   /etc/package -v -c `cat /.package` >/dev/console
+           else
+                   /etc/package -v >/dev/console
+   fi
+   case $? in
+   0)
+           echo "Package completed successfully" >/dev/console 2>&1
+           date >/dev/console 2>&1
+           ;;
+   4)
+           echo "Rebooting to restart system" >/dev/console 2>&1
+           echo >/fastboot
+           shutdown
+           ;;
+   *)
+           echo "Update failed, continuing anyway" >/dev/console 2>&1
+           ;;
+   esac
+   fi
+

Running the package program

After you have created and compiled prototype files and +modified client machines, you are ready to run the package +program. It is probably most convenient to run the package +program automatically at reboot by invoking it in the machine's AFS +initialization file, but you can also issue the command at the command shell +prompt. +

The configuration file must be completely correct. If there are any +syntax errors or incorrect values, the program exits without executing any +instruction. To check the configuration file, issue the +package command with the -noaction and -debug +flags at the command shell prompt. They display a list of potential +problems without actually executing instructions. +

The package program follows these general rules. Complete +explanations are in Package Configuration File Instruction Syntax. +

The package program does not delete any files from the disk +unless the R update code was specified in the prototype +file. If the R update code is associated with the parent +directory, the package program removes anything from the local disk +directory that is not specified in the configuration file. +
Local files are updated only if they are out of date. For each +F instruction in the configuration file, the package +program compares the time of the local file with the indicated source +file. If the source file is newer than the local, the file is +updated. +
When the initialization file is modified as recommended in Modifying Client Machines, the package program reboots the workstation +automatically if any files marked with the Q update code are +updated, and if the package program has been invoked from the +initialization file. When a file marked with the Q update +code is changed, the package program exits with status code 4, +causing a reboot (as directed in the initialization file). Files that +require a reboot before changes are recognized (such as the operating system +kernel and /usr/vice/etc/CellServDB files) must be marked with a +Q update code in the configuration file. +
The package program copies the configuration file it has just +used to /etc/package.sysname, where +sysname reflects this machine's system type. The +package command interpreter consults this file if you do not +provide a configuration file name. To be sure that it configures the +local disk as you wish, review its contents. +

To invoke the package program by rebooting

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
(Recommended) Verify the following: +
- The /.package file identifies the desired configuration +file +
- The package binary is available as /etc/package +
- The initialization file is properly modified to invoke the +package program automatically +
+
Reboot the machine, using the appropriate command. +
```
   # shutdown
+
```
+

+ + +

To invoke the package program directly (without rebooting)

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Verify the following: +
- The /.package file identifies the desired configuration +file +
- The package binary is available as /etc/package +
- The initialization file is properly modified to invoke the +package program automatically +
+
Issue the package command. +
```
   # package  [initcmd]  [-config <base name of configuration file>]  \
+    [-fullconfig <full name of configuration file, or stdin for standard input>]  \
+    [-overwrite]  [-noaction]  [-verbose]  [-silent] [-rebootfiles] 
+
```
+
where +
+
-config +
Specifies the full pathname of the configuration file to use, ending in +the file's base name, which omits the suffix that indicates the machine +type. The package program knows how to determine a +machine's type, and automatically selects the appropriate version of the +base file name. An example of the proper value for this argument is +staff rather than staff.rs_aix42. You can +also have the package program refer to /.package +to learn the configuration file name by providing the following value: +
`cat /.package` +
Use either this argument or the -fullconfig argument. +
-fullconfig +
Specifies the full name of the configuration file to use, complete with +the machine-type extension. Examples are +staff.rs_aix42 and minimal.hp_ux110 +files. +
Another possibility is the string stdin, which indicates that +the issuer is providing configuration information via the standard input +stream, either as a piped file or by typing the configuration file at the +keyboard. Press <Ctrl-d> to conclude the input. +
Use either this argument or the -config argument. +
-overwrite +
Overwrite elements on the local disk with the source version indicated in +the configuration file, even if the first (owner) w +(write) mode bit is turned off on the local disk copy of the +file. Files protected by the I update code are not +overwritten; see the definition for the F instruction. +
-noaction +
Displays on the standard output stream a trace of potential problems in +running the command, rather than actually running it. If the +-verbose flag is added, the trace also notes the actions the +package program attempts. +
-silent +
Explicitly invokes the default level of tracing, which includes only a +list of problems encountered while executing the command. +
-verbose +
Produces a detailed trace of the program's actions on the standard +output stream. The trace records on the transfer and ownership/mode bit +setting of each element in the configuration file. +
-rebootfiles +
Prevents the overwrite of any element marked with the Q +update-mode code in the configuration file. This effectively prevents +the machine from rebooting automatically again when the package +program is invoked from an initialization file. +
+
If you think files marked with the Q update code were updated, +reboot the machine. This reboot does not occur automatically. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd017.htm b/doc/html/AdminGuide/auagd017.htm new file mode 100644 index 0000000..99367eb --- /dev/null +++ b/doc/html/AdminGuide/auagd017.htm @@ -0,0 +1,2501 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

+ +

Creating and Deleting User Accounts with the uss Command Suite

The uss command suite helps you create and delete +AFS user accounts quickly and easily. You can create a single account +with the uss add command, delete a single account with the uss +delete command, or create and delete multiple accounts with the uss +bulk command. +

A single uss add or uss bulk command can create a +complete AFS user account because the uss command interpreter +refers to a template file in which you predefine the configuration of many +account components. The uss delete command deletes most of +the components of a user account, but does not use a template file. +

The uss suite also easily incorporates shell scripts or other +programs that you write to perform parts of account creation and deletion +unique to your site. To invoke a script or program automatically as a +uss command runs, use the appropriate instructions in the template +file or bulk input file. Various sections of this chapter discuss +possible uses for scripts. +

Using the uss commands to create and delete accounts is the +recommended method because it automates and correctly orders most of the +necessary steps. The alternative is to issue a series of separate +commands to the various AFS servers, which requires more careful record +keeping. For instructions, see Administering User Accounts. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + +
Add a single user account + uss add +
Delete a single user account + uss delete +
Add and delete multiple accounts + uss bulk +
+

Overview of the uss Command Suite

The commands in the uss suite help you to +automate the creation and deletion of AFS user accounts: +

The uss add command creates all of the components of an +account, one account at a time. It consults a template file that +defines account configuration. +
The uss delete command deletes the major components of an +account, one account at a time. It does not use a template file, so you +possibly need to perform additional tasks manually. +
The uss bulk command can create and delete multiple +accounts. It refers to a bulk input file that can contain any number of +account-creation and deletion instructions, along with other instructions for +further automating the process. +

+ + +

The Components of an AFS User Account

An AFS user account can have many components. The only two +required components are entries in the Protection Database and Authentication +Database, but the other components add functionality and usability. The +following information also appears in a corresponding section of Administering User Accounts, but is repeated here for your convenience. +

A Protection Database entry defines the username (the name +provided when authenticating with AFS), and maps it to an AFS user ID (AFS +UID), a number that the AFS servers use internally when referencing +users. The Protection Database also tracks the groups to which the user +belongs. For details, see Administering the Protection Database. +
An Authentication Database entry records the user's AFS +password in a scrambled form suitable for use as an encryption key. +
A home volume stores all the files in the user's home +directory together on a single partition of a file server machine. The +volume has an associated quota that limits its size. For a +complete discussion of volumes, see Managing Volumes. +
A mount point makes the contents of the user's volume +visible and accessible in the AFS filespace, and acts as the user's home +directory. For more details about mount points, see About Mounting Volumes. +
Full access permissions on the home directory's access control +list (ACL) and ownership of the directory (as displayed by the UNIX +ls -ld command) enable the user to manage his or her files. +For details on AFS file protection, see Managing Access Control Lists. +
A local password file entry (in the /etc/passwd file +or equivalent) of each AFS client machine enables the user to log in and +access AFS files through the Cache Manager. A subsequent section in +this chapter further discusses local password file entries. +
Other optional configuration files make the account more +convenient to use. Such files help the user log in and log out more +easily, receive electronic mail, print, and so on. +

+ + +

Privilege Requirements for the uss Commands

To issue uss commands successfully, you usually +need all of the standard AFS administrative privileges: membership in +the system:administrators group, inclusion in the +/usr/afs/etc/UserList file on every relevant server machine, and +the ADMIN flag on your Authentication Database entry. For +details on administrative privilege, see Managing Administrative Privilege. + + + + + + + +

Avoiding and Recovering from Errors and Interrupted Operations

As for any complex operation, there are a number of possible +reasons that an account-creation or deletion operation can halt before it +completes. You can easily avoid several of the common reasons by making +the following checks before issuing a uss command: +

Verify that you have all of the administrative privileges you need to +complete an operation, as described in Privilege Requirements for the uss Commands. The instructions for using the uss add, +uss delete, and uss bulk commands include this check as +a step. +
Proofread the template and bulk input files for correct syntax and +acceptable values. For discussion, see Constructing a uss Template File and Constructing a Bulk Input File. +
Do not issue uss commands when you are aware of network, server +machine, or server process outages. Because uss operations +affect so many components of AFS, it is unlikely that the command can succeed +when there are outages. +

Another way to avoid errors that halt an operation is to preview the +uss command by combining the -dryrun flag with the other +arguments to be used on the actual command. The uss command +interpreter generates a screen trace of the actions to be performed by the +actual command, without performing them. +

Using the -dryrun flag reveals many basic errors that can halt +an operation, particularly the ones due to incorrect syntax in the command +line, template file, or bulk input file. It does not catch all possible +errors, however, because the command interpreter is not actually attempting to +perform the actions it is tracing. For example, a Volume Server outage +does not necessarily halt the volume creation step when the -dryrun +flag is included, because the command interpreter is not actually contacting +the server; such an outage halts the actual creation operation. + + + +

When the uss command interpreter encounters error conditions +minor enough that they do not require halting the operation, it usually +generates a message that begins with the string uss: +Warning: and describes the action it is taking to avoid +halting. For example, if a user's Protection Database entry +already exists, the following message appears on the standard output +stream: +

   uss: Warning: User 'user' already in the protection database
+   The uid for user 'user' is AFS UID
+

If an error is more serious, the word Warning does not appear in +the message, which instead describes why the command interpreter cannot +perform the requested action. Not all of these errors cause the +uss operation to halt, but they still require you to take +corrective action. For example, attempting to create a mount point +fails if you lack the necessary permissions on the parent directory's +ACL, or if the mount point pathname in the V instruction's +mount_point field is malformed. However, this error does not +cause the creation operation to halt until later instructions in the template +attempt to install subdirectories or files under the nonexistent mount +point. +

If the command shell prompts returns directly after an error message, then +the error generally was serious enough to halt the operation. When an +error halts account creation or deletion, the best way to recover is to find +and fix the cause, and then reissue the same uss command. + + + + + + +

The following list describes what happens when components of a user's +account already exist when you reissue an account-creation command (the +uss add command, or the uss bulk command when the bulk +input file contains add instructions): +

If the Protection Database entry already exists, a message confirms its +existence and specifies the associated AFS UID. +
If the Authentication Database entry already exists, a message confirms +its existence. +
If the volume and associated Volume Location Database (VLDB) entry already +exist, a message confirms their existence. However, the uss +command interpreter does alter the volume's quota, mount point, or ACL if +any of the relevant fields in the template V instruction have +changed since the command last ran. If the value in the +mount_point field has changed, the command interpreter creates the +new mount point but does not remove any existing mount points. +
If any of the fields in the template A instruction have +changed, the uss command interpreter makes the changes without +comment. +
If a directory, file, or link defined by a template file D, +E, F, L, or S instruction already +exists, the uss command interpreter replaces the existing element +with one that conforms to the template definition. To control whether +the uss command interpreter prompts for confirmation that you wish +to overwrite a given element, use the -overwrite flag to the +uss add or uss bulk command: +
- If you include the -overwrite flag, the command interpreter +automatically overwrites all elements without asking for confirmation. +
- If you omit the flag, the command interpreter prompts once for each +account to ask if you want to overwrite all elements associated with +it. +
+
The command interpreter always reexecutes X instructions in the +template file. If a command's result already holds, reissuing it +has the same effect as reissuing it outside the context of the uss +commands. +

The following describes what happens when a uss delete command +references account components that have already been deleted. +

If the volume and VLDB entry no longer exist, a message confirms their +absence. +
If the Authentication Database entry no longer exists, a message confirms +its absence. +

+ +

Creating Local Password File Entries with uss

To obtain authenticated access to a cell's AFS +filespace, a user must not only have a valid AFS token, but also an entry in +the local password file (/etc/passwd or equivalent) of the AFS +client machine. This section discusses why it is important for the +user's AFS UID to match to the UNIX UID listed in the local password +file, the appropriate value to put in the file's password field, and +outlines a method for creating a single source password file. +

For instructions on using the template file's E instruction +to generate local password file entries automatically as part of account +creation, see Creating a Common Source Password File. +

The following information also appears in a corresponding section of Administering User Accounts, but is repeated here for your convenience. + + + + + +

Assigning AFS and UNIX UIDs that Match

A user account is easiest to administer and use if the AFS +user ID number (AFS UID) and UNIX UID match. All instructions in the +AFS documentation assume that they do. +

The most basic reason to make AFS and UNIX UIDs the same is so that the +owner name reported by the UNIX ls -l and ls -ld +commands makes sense for AFS files and directories. Following standard +UNIX practice, the File Server records a number rather than a username in an +AFS file or directory's owner field: the owner's AFS +UID. When you issue the ls -l command, it translates the UID +to a username according to the mapping in the local password file, not the AFS +Protection Database. If the AFS and UNIX UIDs do not match, the ls +-l command reports an unexpected (and incorrect) owner. The +output can even vary on different client machines if their local password +files map the same UNIX UID to different names. +

Follow the recommendations in the indicated sections to make AFS and UNIX +UIDs match when you are creating accounts for various types of users: +

If creating an AFS account for a user who already has a UNIX UID, see Converting Existing UNIX Accounts with uss. +
If some users in your cell have existing UNIX accounts but the user for +whom you are creating an AFS account does not, then it is best to allow the +Protection Server to allocate an AFS UID automatically. To avoid +overlap of AFS UIDs with existing UNIX UIDs, set the Protection +Database's max user id counter higher than the largest UNIX +UID, using the instructions in Displaying and Setting the AFS UID and GID Counters. +
If none of your users have existing UNIX accounts, allow the Protection +Server to allocate AFS UIDs automatically, starting either at its default or +at the value you have set for the max user id counter. +

+ + +

Specifying Passwords in the Local Password File

Authenticating with AFS is easiest for your users if you +install and configure an AFS-modified login utility, which logs a user into +the local file system and obtains an AFS token in one step. In this +case, the local password file no longer controls a user's ability to +login in most circumstances, because the AFS-modified login utility does not +consult the local password file if the user provides the correct AFS +password. You can nonetheless use a password file entry's password +field (usually, the second field) in the following ways to control login and +authentication: +

To prevent both local login and AFS authentication, place an asterisk ( * +) in the field. This is useful mainly in emergencies, when you want to +prevent a certain user from logging into the machine. +
To prevent login to the local file system if the user does not provide the +correct AFS password, place a character string of any length other than the +standard thirteen characters in the field. This is appropriate if you +want to allow only people with local AFS accounts to log into to your +machines. A single X or other character is the most easily +recognizable way to do this. +
To enable a user to log into the local file system even after providing an +incorrect AFS password, record a standard UNIX encrypted password in the field +by issuing the standard UNIX password-setting command (passwd or +equivalent). +

If you do not use an AFS-modified login utility, you must place a standard +UNIX password in the local password file of every client machine the user will +use. The user logs into the local file system only, and then must issue +the klog command to authenticate with AFS. It is simplest if +the passwords in the local password file and the Authentication Database are +the same, but this is not required. + + + + + +

Creating a Common Source Password File

This section explains how to create a common source version +of the local password file when using uss commands to create user +accounts. The sequence of steps is as follows: +

Include an E instruction in the template file to create a +one-line file that has the format of a local password file entry. +
Incorporate the one-line file into the common source version of the local +password file. It makes sense to store this file in AFS. See the +following two example scripts for automating this step. +
Distribute the common password file to each client machine, perhaps by +using the AFS package utility as described in Configuring Client Machines with the package Program. +

As an example, the template file used by the ABC Corporation includes the +following E instruction to create a file called +passwd_username in the directory +/afs/.abc.com/common/etc/newaccts (the entire +contents of the template file appear in Example uss Templates and a full description of the E instruction +appears in Creating One-Line Files with the E Instruction): +

   E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root \
+        "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
+

For the user Joe L. Smith with username smith, this +instruction creates a file called passwd_smith which contains the +following line: +

   smith:X:1205:11:Joe L. Smith:/afs/abc.com/usr/usr1/smith:/bin/csh
+

A shell script is probably the easiest way to incorporate a set of files +created in this manner into a common source password file, and two sample +shell scripts appear here. To automate the process even further, you +can create a cron process in a file server machine's +/usr/afs/local/BosConfig directory to execute the shell script, +perhaps each day at a given time; for details, see To create and start a new process. +
Note: The following example scripts are suggestions only. If you choose to +use them, or to model similar scripts on them, you must test that your script +has the desired result, preferably in a test environment. +
+

Example C Shell Script +

The first example is a simple C shell script suitable for the ABC +Corporation cell. It incorporates the individual files found in the +/afs/.abc.com/common/uss/newaccts directory into a +new version of the global password file found in the +/afs/.abc.com/common/etc directory, sorting the files +into alphabetical order. It takes care to save the current version with +a .old extension, then removes the individual files when +done. +

   set  dir = /afs/.abc.com/common
+   cat  $dir/uss/newaccts/passwd_* $dir/etc/passwd  >!  $dir/etc/passwd.new
+   mv  $dir/etc/passwd  $dir/etc/passwd.old
+   sort  $dir/etc/passwd.new  >  $dir/etc/passwd
+   rm  $dir/etc/passwd.new  $dir/uss/newaccts/passwd_*
+

Example Bourne Shell Script +

The second, more elaborate, example is a Bourne shell script that first +verifies that there are new passwd_username files to be +incorporated into the global password file. While running, it checks +that each new entry does not already exist. Like the shorter C shell +example, it incorporates the individual files found in the +/afs/.abc.com/common/uss/newaccts directory into a +new version of the global passwd file found in the +/afs/.abc.com/common/etc directory. +

   #!/bin/sh
+   DESTDIR=/afs/.abc.com/common/uss/newaccts
+   cd  $DESTDIR
+   DEST=/afs/.abc.com/common/etc
+   cp /afs/.abc.com/common/etc/passwd   /afs/.abc.com/common/uss/newaccts/passwd
+   echo "copied in passwd file."
+   PASSWD=/afs/.abc.com/common/uss/newaccts/passwd
+   ENTRIES=`ls passwd_*`
+   case $ENTRIES in 
+   "")
+        echo No new entry found to be added to passwd file
+        ;;
+   *)
+        echo  "Adding new users to passwd file."
+        for  i  in  $ENTRIES
+        do
+           cat  $i  |  awk  -F:  '{print $1  >  "foo"}'
+           USER=`cat foo`
+           case  `egrep  -e  \^$USER\: $PASSWD` in 
+           "")
+                   echo  adding  $USER
+                   cat  $i  >>  $PASSWD
+                   ;;
+           *)
+                   echo  $USER already in passwd file
+                   ;;
+           esac
+           mv  $i  ../old.passdir/done_${i}
+        done
+        cd  /afs/.abc.com/common/uss/newaccts
+        echo  "sorting password file"
+        sort  ${PASSWD}  >  ${PASSWD}.sorted
+        echo  "installing files"     
+        install  ${PASSWD}.sorted ${DEST}/passwd
+        echo  "Password file is built, sorted and installed."
+        ;;
+   esac
+

+ + + +

Converting Existing UNIX Accounts with uss

This section discusses the three main issues you need to +consider if there are existing UNIX accounts to be converted to AFS +accounts. +

Making UNIX and AFS UIDs Match

As previously mentioned, AFS users must have an entry in the +local password file on every client machine from which they access the AFS +filespace as an authenticated user. Both administration and use are +much simpler if the UNIX UID and AFS UID match. When converting +existing UNIX accounts, you have two alternatives: +

Make the AFS UIDs match the existing UNIX UIDs. In this case, you +need to assign the AFS UID yourself as you create an AFS account: +
- If using the uss add command, include the -uid +argument. +
- If using the uss bulk command, specify the desired UID in the +uid field of the add instruction in the bulk input +file. +
+
Because you are retaining the user's UNIX UID, you do not need to +alter the UID in the local password file entry. However, if you are +using an AFS-modified login utility, you possibly need to change the password +field in the entry. For a discussion of how the value in the password +field affects login with an AFS-modified login utility, see Creating Local Password File Entries with uss. +
If now or in the future you need to create AFS accounts for users who do +not have an existing UNIX UID, then you must guarantee that new AFS UIDs do +not conflict with any existing UNIX UIDs. The simplest way is to set +the max user id counter in the Protection Database to a value +higher than the largest existing UNIX UID. See Displaying and Setting the AFS UID and GID Counters. +
Change the existing UNIX UIDs to match the new AFS UIDs that the +Protection Server assigns automatically. +
Allow the Protection Server to allocate the AFS UIDs automatically as you +create AFS accounts. For instructions on creating a new entry for the +local password file during account creation, see Creating Local Password File Entries with uss. +
There is one drawback to changing the UNIX UID: any files and +directories that the user owned in the local file system before becoming an +AFS user still have the former UID in their owner field. If you want +the ls -l and ls -ld commands to display the correct +owner, you must use the chown command to change the value to the +user's new UID, whether you are leaving the file in the local file system +or moving it to AFS. See Moving Local Files into AFS. +

Setting the Password Field Appropriately

Existing UNIX accounts already have an entry in the local +password file, probably with a (scrambled) password in the password +field. You possibly need to change the value in the field, depending on +the type of login utility you use: +

If the login utility is not modified for use with AFS, the actual password +must appear (in scrambled form) in the password field of the local password +file entry. +
If the login utility is modified for use with AFS, choose one of the +acceptable values, each of which affects the login utility's behavior +differently. See Creating Local Password File Entries with uss. +

If you choose to place an actual password in a local password file entry, +then you can define a dummy password when you use a template file E +instruction to create the entry, as described in Creating One-Line Files with the E Instruction. Have the user issue the UNIX password-setting +command (passwd or equivalent) to replace the dummy with an actual +secret password. +

Moving Local Files into AFS

New AFS users with existing UNIX accounts probably already +own files and directories stored in a machine's local file system, and it +usually makes sense to transfer them into the new home volume. The +easiest method is to move them onto the local disk of an AFS client machine, +and then use the UNIX mv command to transfer them into the +user's new AFS home directory. +

As you move files and directories into AFS, keep in mind that the meaning +of their mode bits changes. AFS ignores the second and third sets of +mode bits (group and other), and does not use the first set (the owner bits) +directly, but only in conjunction with entries on the ACL (for details, see How AFS Interprets the UNIX Mode Bits). Be sure that the ACL protects the file or directory +at least as securely as the mode bits. +

If you have chosen to change a user's UNIX UID to match a new AFS UID, +you must change the ownership of UNIX files and directories as well. +Only members of the system:administrators group can issue the +chown command on files and directories once they reside in +AFS. + + + +

Constructing a uss Template File

Creating user accounts with uss commands is +generally more convenient than using individual commands. You control +the account creation process just as closely, but the uss template +file enables you to predefine many aspects of account configuration. +Because you construct the template before issuing uss commands, you +have time to consider configuration details carefully and correct syntax +errors. The following list summarizes some further advantages of using +a template: +

You do not have to remember the correct order in which to create or delete +account components, or the order of each command's arguments, which +reduces the likelihood of errors. +
You do not have to type the same information multiple times. +Instead, you can place constants and variables in the template file that +enable you to type as little on the command line as possible. See Using Constants and Variables in the Template File. +
You can create different templates for different types of users. +Instead of having to remember which components differ for a given user, +specify the appropriate template when issuing the uss add or +uss bulk command. +
You can create any of the three types of AFS account (authentication-only, +basic, or full) by including or omitting certain information in the template, +as described in Creating the Three Types of User Accounts. +

The following list briefly describes the instructions that can appear in a +template file and points you to a later section for more details. It +lists them in the order that is usually optimal for correct handling of +dependencies between the different types of instruction. +

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. Place the corresponding template file variable, $AUTO, in +the mount_point field of the V instruction. See Evenly Distributing User Home Directories with the G Instruction and Creating a Volume with the V Instruction. +
V +: Creates a volume, mounts it as the user's home directory at a +specified location in the AFS filespace, sets the volume's quota, and +defines the owner and ACL for the directory. This instruction must +appear in any template that is not empty (zero-length). See Creating a Volume with the V Instruction. +
D +: Creates a directory, generally a subdirectory of the new home directory, +and sets its mode bits, owner, and ACL. See Creating a Directory with the D Instruction. +
F +: Creates a file by copying a prototype and sets its mode bits and +owner. See Creating a File from a Prototype with the F Instruction. +
E +: Creates a single-line file by copying in the contents of the instruction +itself, then sets the file's mode bits and owner. See Creating One-Line Files with the E Instruction. +
L +: Creates a hard link. See Creating Links with the L and S Instructions. +
S +: Creates a symbolic link. See Creating Links with the L and S Instructions. +
A +: Improves account security by imposing restrictions on passwords and +authentication attempts. See Increasing Account Security with the A Instruction. +
X +: Executes a command. See Executing Commands with the X Instruction. +

+ + + +

Creating the Three Types of User Accounts

Using the uss add and uss bulk +commands, you can create three types of accounts that differ in their levels +of functionality. For a description of the types, see Configuring AFS User Accounts. The following list explains how to construct a +template for each type: +

To create an authentication-only account, create an empty (zero-length) +template file. Such an account has only two components: entries +in the Authentication Database and Protection Database. +
To create a basic account, include a V instruction, and +G instructions if you want to distribute home directories evenly as +described in Evenly Distributing User Home Directories with the G Instruction. In addition to Authentication Database and +Protection Database entries, this type of account includes a volume mounted at +the home directory with owner and ACL set appropriately. +
To create a full account, include D, E, +F, L, and S instructions as appropriate, in +addition to the V and G instructions. This type +of account includes configuration files for basic functions such as logging +in, printing, and mail delivery. For a discussion of some useful types +of configuration files, see Creating Standard Files in New AFS Accounts. +

+ + + + +

Using Constants and Variables in the Template File

Each instruction in the uss template file has +several fields that define the characteristics of the element that it +creates. The D instruction's fields, for instance, +define a directory's pathname, owner, mode bits, and ACL. +

You can place three types of values in a field: a variable, a +constant, or a combination of the two. The appropriate value depends on +the desired configuration, and determines which arguments you provide to the +uss add command or which fields you include in a bulk input file +add instruction. +

If an aspect of account configuration is the same for every user, define a +constant value in the appropriate field by inserting a character +string. For example, to assign a space quota of 10,000 KB to every user +volume, place the string 10000 in the V +instruction's quota field. +

If, on the other hand, an aspect of account configuration varies for each +user, put a variable in the appropriate field. When creating each +account, provide a value for the variable by providing either the +corresponding argument to the uss add command or a value in the +corresponding field of the add instruction in the bulk input +file. +

The uss command suite defines a set of template variables, each +of which has a corresponding source for its value, as summarized in Table 3. For a discussion of their intended uses, see the +following sections about each template instruction (Creating a Volume with the V Instruction through Executing Commands with the X Instruction). +
+

Table 3. Source for values of uss template variables
+ + + + + + + + + + + +
Variable + Source for value +
$AUTO + Previous G instructions in template +
$MTPT + -mount argument to uss add command or +mount_point field of bulk input file add instruction, when +in V instruction; V instruction's +mount_point field when in subsequent instructions +
$NAME + -realname argument to uss add command or +mount_point field of bulk input file add instruction, if +provided; otherwise, -user argument to uss add +command or username field of in bulk input file add +instruction +
$PART + -partition argument to uss add command or +partition field of bulk input file add instruction +
$PWEXPIRES + -pwexpires argument to uss add command or +password_expires field of bulk input file add instruction +
$SERVER + -server argument to uss add command or +file_server field of bulk input file add instruction +
$UID + -uid argument to uss add command or uid +field of bulk input file add instruction, if provided; +otherwise, allocated automatically by Protection Server +
$USER + -user argument to uss add command or +username field of bulk input file add instruction +
$1 through $9 + -var argument to uss add command or var1 +through var9 fields of bulk input file add instruction +
+

A common use of variables is to define the file server machine and +partition that house the user's volume, which often vary from user to +user. Place the $SERVER variable in the V instruction's +server field, and the $PART variable in its partition +field. If using the uss add command, provide the desired +value with the -server and -partition arguments. +If using the uss bulk command, provide the desired values in the +file_server and partition fields of each user's +add instruction in the bulk input file. + + +

The variables $1 through $9 can be used to customize other aspects of the +account. Provide a value for these variables with the -var +argument to the uss add command or in the appropriate field of the +bulk input file add instruction. The -var +argument is unusual in that each instance for it has two parts: the +number index and the value, separated by a space. For examples of the +use of a number variable, see the discussions of the mount_point and +quota fields in Creating a Volume with the V Instruction. +

If some aspect of account configuration is partly constant and partly +variable, you can combine variables and constants in an instruction +field. For example, suppose that the ABC Corporation mounts user +volumes in the /afs/abc.com/usr directory. That part +of the pathname is constant, but the name of the mount point and home +directory is the user's username, which corresponds to the $USER +variable. To configure accounts in this way, combine a constant string +and a variable in the V instruction's mount_point +field as follows: +

   /afs/abc.com/usr/$USER
+

Then provide the value for the $USER variable with the -user +argument to the uss add command, or in the username field +of each user's add instruction in the bulk input file. + + +

Where to Place Template Files

A template must be available to the uss command +interpreter as it executes a uss add or uss bulk +command, even if it is the zero-length file appropriate for creating an +authentication-only account. +

If you do not provide the -template argument to the uss +add or uss bulk command, then the command interpreter +searches for a template file called uss.template in each of +the following directories in turn: +

The current working directory +
/afs/cellname/common/uss, where cellname is +the local cell +
/etc +

To use a template file with a different name or stored in a different +directory, include the -template argument to the uss add +or uss bulk command. If you provide a filename only, the +command interpreter looks for it in the directories listed just +previously. If you provide a pathname and filename, it looks only in +the specified directory, interpreting a partial pathname relative to the +current working directory. + + +

Some General Rules for Constructing a Template

This section summarizes some general rules to follow when +constructing a template file. For each instruction's syntax +definition, see the following sections (Evenly Distributing User Home Directories with the G Instruction through Executing Commands with the X Instruction). +

If a variable takes its value from an element elsewhere within the +template, the definition must precede the reference. Putting the +instruction lines in the following order usually results in correct resolution +of variables: +
G V D F E L S A X +
The fields in each instruction must appear in the order specified by the +instruction's syntax definition, which appear in the following sections +about each instruction. You cannot omit a field. Separate each +field from its neighbors with one or more spaces. +
When specifying a pathname, provide a full one. Partial pathnames +are interpreted relative to the current working directory (the one in which +the uss command is issued), with possibly unintended +results. +
Each instruction must appear on a single line in the template file, with a +newline character (<Return>) only at the end of the +instruction. Some example instructions appear in this document on more +than one line, but that is only for legibility. +
Provide a value for every variable that appears in the template by +including the corresponding argument to the uss add command or +placing a value in the corresponding field of the bulk input file +add instruction. A missing value halts the entire creation +operation. If a variable does not appear in the template file, the +command interpreter ignores the corresponding command-line argument or field +in the bulk input file, even if you provide it. +
You can use blank lines in the template file to increase its +legibility. If you place comments in the file, begin each comment line +with the number sign (#). +

About Creating Local Disk Directories and Files

It is possible to use the D, E, and +F instructions to create directories or files in the local file +system of the machine on which you are issuing the uss command, but +that usage is not recommended. It introduces two potential +complications: +

The local file system automatically assigns ownership of a new local disk +directory or file to its creator. Because you are the issuer of the +uss command that is creating the object, it records your current +UNIX UID. If that is not appropriate and you want to designate another +owner as the object is created, then you must be logged in as the local +superuser root (the local file system allows only the +root user to issue the UNIX chown command, which the +uss command interpreter invokes to change the owner from the +default value). You must also use the -admin argument to the +uss add or uss bulk command to authenticate as a +privileged AFS administrator. Only an administrator can create +Authentication Database and Protection Database entries, which the +uss command interpreter always creates as part of a new +account. +
The alternative is to become the local superuser root after the +uss operation completes, and issue the necessary chown +command then. However, that makes the account creation process that +much less automated. +
Creating a local disk directory always generates an error message because +the uss command interpreter cannot successfully set a local +directory's ACL. The directory is created nevertheless, and a +value still must appear in the D instruction's ACL +field. +

The recommended method for configuring a machine's local disk is to +use the AFS package utility instead; see Configuring Client Machines with the package Program. + + +

Example uss Templates

This section describes example templates for the basic and +full account types (the template for an authentication-only account is +empty). +

The first example creates a basic account. It contains two +G instructions and a V instruction that defines the +volume name, file server machine, partition, quota in kilobytes, mount point, +home directory owner, and home directory access control list. In the +ABC Corporation cell, a suitable template is: +

   G /afs/.abc.com/usr1
+   G /afs/.abc.com/usr2
+   V  user.$USER  $SERVER.abc.com  /vicep$PART  5000  $AUTO/$USER   $UID  \
+        $USER all staff rl
+

When issuing the uss add command with this type of template, +provide the following arguments: +

-user to specify the username for the $USER variable +
-server to specify the unique part of the file server machine +name for the $SERVER variable +
-partition to specify the unique part of the partition name for +the $PART variable +

The Protection Server automatically assigns an AFS UID for the $UID +variable, and the G instructions provide a value for the $AUTO +variable. +

The following example template file creates a full account in the ABC +Corporation cell. The following sections about each type of instruction +describe the effect of the examples. Note that the V and +E instructions appear on two lines each only for the sake of +legibility. +

   #
+   # Specify the available grouping directories
+   #
+   G /afs/.abc.com/usr1
+   G /afs/.abc.com/usr2
+   #
+   # Create the user's home volume
+   #
+   V user.$USER $SERVER.abc.com /vicep$PART 5000 /afs/.abc.com/$AUTO/$USER \
+        $UID $USER all abc:staff rl
+   #
+   # Create directories and files for mail
+   #
+   D $MTPT/.MESSAGES 0700 $UID $USER all abc:staff none 
+   D $MTPT/.Outgoing 0700 $UID $USER rlidwk postman rlidwk 
+   D $MTPT/Mailbox 0700 $UID $USER all abc:staff none system:anyuser lik
+   #
+   # Here are some useful scripts for login etc.
+   #
+   F $MTPT/.Xbiff 0755 $UID /afs/abc.com/admin/user/proto
+   F $MTPT/.Xresources 0644 $UID /afs/abc.com/admin/user/proto
+   F $MTPT/.Xsession 0755 $UID /afs/abc.com/admin/user/proto
+   F $MTPT/.cshrc 0755 $UID /afs/abc.com/admin/user/proto
+   F $MTPT/.login 0755 $UID /afs/abc.com/admin/user/proto
+   F $MTPT/.logout 0755 $UID /afs/abc.com/admin/user/proto
+   F $MTPT/.twmrc 0644 $UID /afs/abc.com/admin/user/proto
+   F $MTPT/preferences 0644 $UID /afs/abc.com/admin/user/proto
+   #
+   # Make a passwd entry
+   #
+   E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root \
+        "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
+   #
+   # Put in the standard password/authentication checks
+   #
+   A $USER 250 noreuse 9 25
+   #
+   # Create and mount a public volume for the user
+   #
+   X "create_public_vol $USER $1 $2"
+   #
+   # Here we set up the symbolic link to public directory
+   #
+   S /afs/abc.com/public/$USER $MTPT/public
+

+ + + + + +

Evenly Distributing User Home Directories with the G Instruction

In cells with thousands of user accounts, it often makes +sense to distribute the mount points for user volumes into multiple parent +directories, because placing them all in one directory noticeably slows down +directory lookup when a user home directory is accessed. A possible +solution is to create parent directories that group user home directories +alphabetically, or that reflect divisions like academic or corporate +departments. However, in a really large cell, some such groups can +still be large enough to slow directory lookup, and users who belong to those +groups are unfairly penalized every time they access their home +directory. Another drawback to groupings that reflect workplace +divisions is that you must move mount points when users change departmental +affiliation. +

An alternative is an even distribution of user home directories into +multiple parent directories that do not represent workplace divisions. +The uss command suite enables you to define a list of directories +by placing a G instruction for each one at the top of the template +file, and then using the $AUTO variable in the V instruction's +mount_point field. When the uss command interpreter +encounters the $AUTO variable, it substitutes the directory named by a +G instruction that currently has the fewest entries. +(Actually, the $AUTO variable can appear in any field that includes a +pathname, in any type of instruction. In all cases, the command +interpreter substitutes the directory that currently has the fewest +entries.) +

The G instruction's syntax is as follows: +

   G  directory
+

where directory specifies either a complete directory pathname or +only the final element (the directory itself). The choice determines +the appropriate value to place in the V instruction's +mount_point field. +

Specify the read/write path to each directory, to avoid the failure that +results when you attempt to create a new mount point in a read-only +volume. By convention, you indicate the read/write path 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 Mounting Volumes. +

For example, the ABC Corporation example template for a full account in Example uss Templates defines two directories: +

   G /afs/.abc.com/usr1
+   G /afs/.abc.com/usr2
+

and puts the value $AUTO/$USER in the V +instruction's mount_point field. An alternative with the +same result is to define the directories as follows: +

   G usr1
+   G usr2
+

and specify a more complete pathname in the V instruction's +mount_point field: +/afs/.abc.com/$AUTO/$USER. + + + + + + +

Creating a Volume with the V Instruction

Unless the template file is empty (zero-length), one and +only one V instruction must appear in it. (To create other +volumes for a user as part of a uss account-creation operation, use +the X instruction to invoke the vos create command or a +script that invokes that command along with others, such as the fs +mkmount command. For an example, see Executing Commands with the X Instruction.) +

The V instruction defines the following AFS entities: +

A volume and associated VLDB entry +
The volume's site (file server machine and partition) +
The volume's mount point in the AFS filespace, which becomes the +user's home directory +
The volume's space quota +
The home directory's owner, usually the new user +
The home directory's ACL, which normally at least grants all +permissions to the user +

The following discussion of the fields in a V instruction refers +to the example in the full account template from Example uss Templates (the instruction appears here on two lines only for +legibility): +

   V  user.$USER  $SERVER.abc.com  /vicep$PART  5000  \
+       /afs/.abc.com/$AUTO/$USER  $UID  $USER all abc:staff rl
+

The V instruction's syntax is as follows: +

   V  volume_name  server  partition  quota  mount_point owner  ACL
+

where +

V +

Indicates a volume creation instruction. +

volume_name +

Specifies the volume's name as recorded in the VLDB. +

To follow the convention of including the user's name as part of the +volume name, include the $USER variable in this field. The variable +takes its value from the -user argument to the uss add +command or from the bulk input file add instruction's +username field. +

The ABC Corporation example uses the value user.$USER to +assign the conventional volume name, +user.username. When creating an account for +user smith, for example, you then include -user smith as +an argument to the uss add command, or place the value +smith in the bulk input file add instruction's +username field. +

server +

Names the file server machine on which to create the new volume. It +is best to provide a fully qualified host name (for example, +fs1.abc.com), but an abbreviated form is acceptable +if the cell's naming service is available to resolve it at the time the +volume is created. +

To place different users' volumes on different file server machines, +use the $SERVER variable in this field, and provide a value for it either with +the -server argument to the uss add command or in the +server field of the bulk input file add +instruction. One easy way to specify a fully qualified hostname without +having to type it completely on the command line is to combine a constant and +the $SERVER variable. Specifically, the constant specifies the +domain-name suffix common to all the file server machines. +

In the ABC Corporation example, all of the file server machines in the cell +share the abc.com domain name suffix, so the server +field combines a variable and constant: +$SERVER.abc.com. To place the new volume on +the machine fs1.abc.com, you then include +-server fs1 as an argument to the uss add command, or +place the value fs1 in the bulk input file add +instruction's server field. +

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 one of the abbreviations listed in Rules for Using Abbreviations and Aliases. +

To place different users' volumes on different partitions, use the +$PART variable in this field, and provide a value for it either with the +-partition argument to the uss add command or in the +partition field of the bulk input file add +instruction. Because all full partition names start with the +/vicep string, it is convenient to combine that string as a +constant with the $PART variable. +

The ABC Corporation example template combines the constant string +/vicep and the $PART variable in this way, as +/vicep$PART. + + + + +

quota +

Sets the maximum number of kilobyte blocks the volume can occupy on the +file server machine's disk. It must be an integer. If you +assign the same quota to all user volumes, specify a constant value. To +assign different quotas to different volumes, place one of the number +variables ($1 through $9) in this field, and provide a value for it either +with the -var argument to the uss add command or in the +appropriate field of the bulk input file add instruction. +

The ABC Corporation example grants a 5000 KB initial quota to every new +user. + + + + +

mount_point +

Creates a mount point for the volume, which serves as the volume's +root directory and the user's home directory. By convention, user +home directory names include the username, which you can read in by including +the $USER variable in this field. +

Specify the read/write path to the mount point, to avoid the failure that +results when you attempt to create the new mount point in a read-only +volume. By convention, you indicate the read/write path by placing a +period before the cell name at the pathname's second level (for example, +/afs/.abc.com). If you use the $AUTO variable +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 Mounting Volumes. +

If other parts of the mount point name also vary from user to user, you can +use the $MTPT variable in this field, and provide a value with the uss +add command's -mount argument or in the +mount_point field of a bulk input file add +instruction. Note, however, that when the $MTPT variable appears in +subsequent instructions in the template (usually, in D, +E, or F instructions), it instead takes as its value the +complete contents of this field. +

Combine constants and variables based on how you have decided to group home +directories together in one or more parent directories. Note that the +parent directories must already exist before you run a uss add or +uss bulk command that references the template. Possibilities +for grouping home directories include the following: + +

Placing all user home directories in a single parent directory; the +name /afs/cellname/usr is an AFS-appropriate +variation on the UNIX /usr convention. This choice is most +appropriate for a cell with a small number of user accounts. The +simplest way to implement this choice is to combine a constant string and the +$USER variable, as in /afs/.abc.com/usr/$USER. +
Distributing home directories evenly into a set of parent directories that +do not correspond to workplace divisions. This choice is appropriate in +cells with tens of thousands of accounts, where the number of home directories +is large enough to slow directory lookup significantly if they all reside +together in one parent directory, but distribution according to workplace +divisions is not feasible. +
The $AUTO variable is designed to distribute home directories evenly in +this manner. As explained in Evenly Distributing User Home Directories with the G Instruction, the uss command interpreter substitutes the +directory that is defined by a preceding G template instruction and +that currently has the fewest entries. The example ABC Corporation +template illustrates this choice by using the value +/afs/.abc.com/$AUTO/$USER. +
Distributing home directories into multiple directories that reflect +divisions like academic or corporate departments. Perhaps the simplest +way to implement this scheme is to use the $MTPT variable to represent the +department, as in +/afs/.ghi.com/usr/$MTPT/$USER. You then +provide -user smith and -mount acctg arguments to the +uss add command to create the mount point +/afs/.ghi.com/usr/acctg/smith. +
Distributing home directories into alphabetic subdirectories of +usr (usr/a, usr/b and so on), based on the +first letter or letters in the username. The advantage is that knowing +the username enables you easily to locate a home directory. A potential +drawback is that the distribution is not likely to be even, and if there are a +large number of accounts, then slowed directory lookup unfairly affects users +whose names begins with popular letters. +
Perhaps the simplest way to implement this scheme is to use the $MTPT +variable to represent the letter or letters, as in +/afs/.jkl.com/usr/$MTPT/$USER. Then provide +the -user smith and -mount s/m arguments to the uss +add command to create the mount point +/afs/.jkl.com/usr/s/m/smith. +

owner +

Specifies the username or UID of the user to be designated the mount +point's owner in the output from the UNIX ls -ld +command. To follow the standard convention for home directory +ownership, use the $UID variable in this field, as in the ABC Corporation +example template. The Protection Server then automatically assigns an +AFS UID unless you provide the -uid argument to the uss +add command or fill in the uid field in the bulk input file +add instruction. (If you are converting existing UNIX +accounts, see the discussion of additional considerations in Converting Existing UNIX Accounts with uss.) + + + + +

ACL +

Sets the ACL on the new home directory. Provide one or more paired +values, each pair consisting of an AFS username or group name and the desired +permissions, in that order (a group name must already exist in the Protection +Database to be used). Separate the two parts of the pair, and each +pair, with a space. For a discussion of the available permissions, see The AFS ACL Permissions. +

At minimum, grant all permissions to the new user by including the value +$USER all in this field. The File Server automatically +grants all permissions to the system:administrators group as +well. You cannot grant permissions to the issuer of the uss +command, because as the last step in account creation the uss +command interpreter automatically deletes that user from any ACLs set during +the creation process. +

The ABC Corporation example uses the following value to grant all +permissions to the new user and r (read) and +l (lookup) permissions to the members of the +abc:staff group: +

$USER all abc:staff rl +

+ + + + + + +

Creating a Directory with the D Instruction

Each D instruction in the template file creates a +directory; there is no limit on the number of them in the +template. If a D instruction creates a subdirectory in a new +user's home directory (its intended use), then it must follow the +V instruction. Creating a directory on the local disk of the +machine where the uss command runs is not recommended for the +reasons outlined in About Creating Local Disk Directories and Files. +

The following discussion of the fields in a D instruction refers +to one of the examples in the full account template in Example uss Templates: +

   D $MTPT/Mailbox 0700 $UID $USER all abc:staff none  system:anyuser lik
+

The D instruction's syntax is as follows: +

   D  pathname  mode_bits  owner  ACL
+

where +

D +

Indicates a directory creation instruction. +

pathname +

Specifies the directory's full pathname. If it is a +subdirectory of the user's home directory, it is simplest to use the +$MTPT variable to specify the home directory pathname. When the $MTPT +variable appears in a D instruction, it takes its value from the +preceding V instruction's mount_point field (this +dependency is why a D instruction must follow the V +instruction). +

Specify the read/write pathname to the directory, to avoid the failure that +results when you attempt to create a new directory in a read-only +volume. By convention, you indicate the read/write path by placing a +period before the cell name at the pathname's second level (for example, +/afs/.abc.com). If you use the $MTPT variable +in this field, the value in the V instruction's +mount_point field possibly already indicates the read/write +path. For further discussion of the concept of read/write and read-only +paths through the filespace, see Mounting Volumes. +

The ABC Corporation example uses the value $MTPT/Mailbox to +place the Mailbox subdirectory in the user's home +directory. +

mode_bits +

Defines the directory's UNIX mode bits. Acceptable values are +the standard three- or four-digit numbers corresponding to a combination of +permissions. Examples: 0755 corresponds to +rwxr-xr-x, and 0644 to rw-r--r--. The +first (owner) x bit must be turned on to enable access to a +directory. +

The ABC Corporation example uses the value 0700 to set the mode +bits on the Mailbox subdirectory to rwxr-----. +

owner +

Specifies the username or 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, as +in the ABC Corporation example template. The Protection Server then +automatically assigns an AFS UID unless you provide the -uid +argument to the uss add command or fill in the uid field +in the bulk input file add instruction. (If you are +converting existing UNIX accounts, see the discussion of additional +considerations in Converting Existing UNIX Accounts with uss.) +

If the directory resides on the local disk, it is simplest to specify the +username or UNIX UID under which you are issuing the uss +command. For a discussion of the complications that arise from +designating another user, see About Creating Local Disk Directories and Files. + + + + +

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 (a group name must already exist in the Protection +Database to be used). Separate the two parts of the pair, and each +pair, with a space. For a description of the available permissions, see +The AFS ACL Permissions. +

At minimum, grant all permissions to the new user by including the value +$USER all. You cannot grant permissions to the issuer of the +uss command, because as the last step in account creation the +uss command interpreter automatically deletes that user from any +ACLs set during the creation process. An error message always appears +if the directory is on the local disk, as detailed in About Creating Local Disk Directories and Files. +

The ABC Corporation example uses the following value to grant all +permissions to the new user, no permissions to the members of the +abc:staff group, and the l (lookup), +i (insert), and k (lock) +permissions to the members of the system:anyuser group: +

$USER all abc:staff none system:anyuser lik +

It grants such extensive permissions to the system:anyuser +group to enable any system user (including a mail-delivery daemon) to insert +mail into the Mailbox directory. The absence of the +r (read) permission prevents members of the +system:anyuser group from reading the mail files. +

+ + + + + + +

Creating a File from a Prototype with the F Instruction

Each F instruction in the template file creates a +file by copying the contents of an existing prototype file; there is no +limit on the number of them in the template, and each can refer to a different +prototype. If an F instruction creates a file in a new +user's home directory or a subdirectory of it (the intended use), then it +must follow the V or D instruction that creates the +parent directory. Creating a file on the local disk of the machine +where the uss command runs is not recommended for the reasons +detailed in About Creating Local Disk Directories and Files. +

The E instruction also creates a file, but the two types of +instruction have complementary advantages. Files created with an +E instruction can be customized for each user, because variables +can appear in the field that specifies the contents of the file. In +contrast, the contents of a file created using the F instruction +are the same for every user. An E file can be only a single +line, however, whereas an F file can be any length. +

The following discussion of the fields in a F instruction refers +to one of the examples in the full account template in Example uss Templates: +

   F $MTPT/.login 0755 $UID /afs/abc.com/admin/user/proto
+

The F instruction's syntax is as follows: +

   F  pathname  mode_bits  owner  prototype_file
+

where +

F +

Indicates a file creation instruction. +

pathname +

Specifies the full pathname of the file to create, including the +filename. If it resides in the user's home directory or a +subdirectory of it, it is simplest to use the $MTPT variable to specify the +home directory pathname. When the $MTPT variable appears in an +F instruction, it takes its value from the preceding V +instruction's mount_point field (this dependency is why an +F instruction must follow the V instruction). +

Specify the read/write path to the file, to avoid the failure that results +when you attempt to create a new file in a read-only volume. By +convention, you indicate the read/write path by placing a period before the +cell name at the pathname's second level (for example, +/afs/.abc.com). If you use the $MTPT variable +in this field, the value in the V instruction's +mount_point field possibly already indicates the read/write +path. For further discussion of the concept of read/write and read-only +paths through the filespace, see Mounting Volumes. +

The ABC Corporation example uses the value $MTPT/.login +to place a file called .login in the user's home +directory. +

mode_bits +

Defines the file's UNIX mode bits. Acceptable values are the +standard three- or four-digit numbers corresponding to a combination of +permissions. Examples: 0755 corresponds to +rwxr-xr-x, and 0644 to rw-r--r--. +

The ABC Corporation example uses the value 0755 to set the mode +bits on the .login file to rwxr-xr-x. +

owner +

Specifies the username or 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, as in +the ABC Corporation example template. The Protection Server then +automatically assigns an AFS UID unless you provide the -uid +argument to the uss add command or fill in the uid field +in the bulk input file add instruction. (If you are +converting existing UNIX accounts, see the discussion of additional +considerations in Converting Existing UNIX Accounts with uss.) +

If the file resides on the local disk, it is simplest to specify the +username or UNIX UID under which you are issuing the uss +command. For a discussion of the complications that arise from +designating another user, see About Creating Local Disk Directories and Files. +

prototype_file +

Names the AFS or local directory that houses the prototype file to +copy. The prototype file's name must match the final element in +the pathname field. +

The ABC Corporation example references a prototype file called +.login in the directory +/afs/abc.com/admin/user/proto. +

+ + + + + + +

Creating One-Line Files with the E Instruction

Each E instruction in the template file creates a +file by echoing a specified single line into it; there is no limit on the +number of them in the template. If an E instruction creates +a file in a new user's home directory or a subdirectory of it (the +intended use), then it must follow the V or D +instruction that creates the parent directory. Creating a file on the +local disk of the machine where the uss command runs is not +recommended for the reasons detailed in About Creating Local Disk Directories and Files. +

The F instruction also creates a file, but the two types of +instruction have complementary advantages. Files created with an +E instruction can be customized for each user, because variables +can appear in the field that specifies the contents of the file. The +command interpreter replaces the variables with appropriate values before +creating the file. In contrast, the contents of a file created using +the F instruction are the same for every user. An +E file can be only a single line, however, whereas an F +file can be any length. +

The E instruction is particularly suited to creating an entry +for the new user in the cell's common source password file, which is then +copied to client machines to serve as the local password file +(/etc/passwd or equivalent). The following discussion of the +fields refers to an example of this type of use, from the ABC +Corporation's full account template shown in Example uss Templates. For further discussion of how to +incorporate the files created in this way into a common source password file, +see Creating a Common Source Password File. +

   E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root  \
+      "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
+

The E instruction's syntax is as follows: +

   E  pathname  mode_bits  owner  "contents"
+

where +

E +

Indicates a file creation instruction. +

pathname +

Specifies the full pathname of the file to create, including the +filename. It can include variables. If it resides in the +user's home directory or a subdirectory of it, it is simplest to use the +$MTPT variable to specify the home directory pathname. When the $MTPT +variable appears in an E instruction, it takes its value from the +preceding V instruction's mount_point field (this +dependency is why an E instruction must follow the V +instruction.) +

The ABC Corporation example writes the file created by the E +instruction to /afs/.abc.com/common/etc/newaccts +directory, naming it after the new user: +

   /afs/.abc.com/common/etc/newaccts/passwd_$USER
+

mode_bits +

The ABC Corporation example uses the value 0644 to set the mode +bits on the passwd_user file to +r-xr--r--. +

owner +

Specifies the username or 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 and is to be owned by the user, place the $UID +variable in this field. The Protection Server then automatically +assigns an AFS UID unless you provide the -uid argument to the +uss add command or fill in the uid field in the bulk input +file add instruction. (If you are converting existing UNIX +accounts, see the discussion of additional considerations in Converting Existing UNIX Accounts with uss.) +

If the file resides on the local disk, specify the username or UNIX UID +under which you are issuing the uss command. For a +discussion of the complications that arise from designating another user, see About Creating Local Disk Directories and Files. +

The ABC Corporation example is creating an AFS file intended for +incorporation into the common password file, rather than for direct use by the +new user. It therefore designates the local superuser root +as the owner of the new file. Designating an alternate owner on an AFS +file does not introduce complications: issuing the chown +command on AFS files requires membership in the +system:administrators group, but the issuer of the +uss command is necessarily authenticated as a member of that +group. +

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 ABC Corporation example has the following value in the +contents field, to create a password file entry: +

   $USER:X:$UID:10:$NAME:$MTPT:/bin/csh
+

+ + + + + + + + + + + +

Creating Links with the L and S Instructions

Each L instruction in the 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. +An explanation of links is beyond the scope of this document, but the basic +effect in both cases is to create a second name for an existing file, so that +it can be accessed via either name. Creating a link does not create a +second copy of the file. +

There is no limit on the number of L or S +instructions in a template file. If the link is in a new user's +home directory or a subdirectory of it (the intended use), then it must follow +the V or D instruction that creates the parent +directory, and the F, E, or X instruction +that creates the file being linked to. Creating a file on the local +disk of the machine where the uss command runs is not recommended, +for the reasons detailed in About Creating Local Disk Directories and Files. +

Note that AFS allows hard links only between files that reside in the same +directory. This restriction is necessary to eliminate the confusion +that results from associating two potentially different ACLs (those of the two +directories) with the same file. Symbolic links are legal between two +files that reside in different directories and even in different +volumes. The ACL on the actual file applies to the link as well. +

You do not set the owner or mode bits on a link created with an +L or S instruction, as you do for directories or +files. The uss command interpreter automatically records the +UNIX UID of the uss command's issuer as the owner, and sets +the mode bits to lrwxrwxrwx (777). +

The following discussion of the fields in an L or S +instruction refers to an example in the full account template from Example uss Templates, namely +

   S /afs/abc.com/public/$USER $MTPT/public
+

The L and S instructions' syntax is as +follows: +

   L  existing_file  link
+   S  existing_file  link
+

where +

L +

Indicates a hard link creation instruction. +

S +

Indicates a symbolic link creation instruction. +

existing_file +

Specifies the complete pathname of the existing file. If it resides +in the user's home directory or a subdirectory of it, it is simplest to +use the $MTPT variable to specify the home directory pathname. When the +$MTPT variable appears in an L or S instruction, it +takes its value from the preceding V instruction's +mount_point field (this dependency is why the instruction must follow +the V instruction). +

Do not create a symbolic link to a file whose name begins with the number +sign (#) or percent sign (%). When the Cache +Manager reads a symbolic link whose contents begin with one of those +characters, it interprets it as a regular or read/write mount point, +respectively. +

The ABC Corporation example creates a link to the publicly readable volume +created and mounted by a preceding X instruction, by specifying the +path to its mount point: +

   /afs/abc.com/public/$USER
+

link +

Specifies the complete pathname of the second name for the file. If +it resides in the user's home directory or a subdirectory of it, it is +simplest to use the $MTPT variable to specify the home directory +pathname. +

Specify the read/write path to the link, to avoid the failure that results +when you attempt to create a new link in a read-only volume. By +convention, you indicate the read/write path by placing a period before the +cell name at the pathname's second level (for example, +/afs/.abc.com). If you use the $MTPT variable +in this field, the value in the V instruction's +mount_point field possibly already indicates the read/write +path. For further discussion of the concept of read/write and read-only +paths through the filespace, see Mounting Volumes. +

The ABC Corporation example creates a link called public in the +user's home directory: +

   $MTPT/public
+

+ + + + +

Increasing Account Security with the A Instruction

The A instruction in the template file enhances +cell security by imposing the following restrictions on users' password +choice and authentication attempts. +

Limiting the user's password lifetime. When the lifetime +expires, the user can no longer use the password to authenticate 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 following discussion of the fields in an A instruction +refers to the example in the full account template from Example uss Templates, which sets a password lifetime of 250 days, prohibits reuse +of passwords, limits the number of failed authentication attempts to nine, and +creates a lockout time of 25 minutes if the authentication limit is +exceeded: +

   A $USER 250 noreuse 9 25
+

The A instruction's syntax is as follows: +

   A  username  password_lifetime  password_reuse  failures  locktime
+

where +

A +

Indicates a security enhancing instruction. +

username +

Names the Authentication Database entry on which to impose security +restrictions. Use the $USER variable to read in the username from the +uss add command's -user argument, or from the +username field of an add instruction in the bulk input +file. The ABC Corporation example uses this value. +

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, by default the user's +password never expires. +

The ABC Corporation example sets a password lifetime of 250 days. +

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 his or her last 20 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. +

The ABC Corporation example prohibits password reuse. +

failures +

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. +

The ABC Corporation example sets the limit to nine failed attempts. +

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 nonzero value to the next highest multiple of 8.5 +minutes. A value of 0 (zero) sets an infinite lockout time, +in which case an administrator must always issue the kas unlock +command to unlock the account. +

The ABC Corporation example sets the lockout time to 25 minutes, which is +rounded up to 25 minutes 30 seconds (the next highest multiple of 8.5 +minutes). +

+ + + + + + +

Executing Commands with the X Instruction

The X instruction in the template file executes a +command, which can be a standard UNIX command, a shell script or program, or +an AFS command. The command string can include standard template +variables, and any number of X instructions can appear in a +template file. If an instruction manipulates an element created by +another instruction, it must appear after that instruction. +

The following discussion of the field in an X instruction refers +to the example in the full account template from Example uss Templates: +

   X "create_public_vol $USER $1 $2"
+

The X instruction's syntax is as follows: +

   X "command"
+

where command specifies the command to execute. Surround it +with double quotes if it contains spaces. The command string can +contain any of the standard variables, which the uss command +interpreter resolves before passing the command on to the appropriate other +command interpreter, but it cannot contain newline characters. +

The ABC Corporation example invokes a script called +create_public_vol, which creates another volume associated with the +new user and mounts it in a publicly readable part of the ABC +Corporation's filespace: +

   "create_public_vol $USER $1 $2"
+

It uses the $USER variable to read in the username and make it part of both +the volume name and mount point name. The uss command issuer +supplies a file server machine name for the $1 variable and a partition name +for the $2 variable, to specify the site for the new volume. + + + + + + + + + + + +

Creating Individual Accounts with the uss add Command

After you have created a template file, you can create an +individual account by issuing the uss add command (for template +creation instructions see Constructing a uss Template File). When you issue the command, the uss +command interpreter contacts various AFS servers to perform the following +actions: +

Create a Protection Database entry. By default, the Protection +Server assigns an AFS UID which becomes the value of the $UID variable used in +the template. +
Create an Authentication Database entry, recording an encrypted version of +the initial password. +
Create the account components defined in the indicated template file, +contacting the File Server, Volume Server, and Volume Location (VL) Server as +necessary. +

To review which types of instructions to include in a template to create +different file system objects, see Constructing a uss Template File. If the template is empty, the uss add +command creates an authentication-only account consisting of Protection +Database and Authentication Database entries. +

When you issue the uss add command, provide a value for each +variable in the template file by including the corresponding command-line +argument. If you fail to supply a value for a variable, the +uss command interpreter substitutes a null string, which usually +causes the account creation to fail. If you include a command line +argument for which the corresponding variable does not appear in the template, +it is ignored. +

Table 4 summarizes the mappings between variables and the arguments +to the uss add command. It is adapted from Table 3, but includes only those variables that take their value +from command line arguments. +
+

Table 4. Command-line argument sources for uss template variables
+ + + + + + + + + + +
Variable + Command-line Argument +
$MTPT + -mount (for occurrence in V instruction) +
$NAME + -realname if provided; otherwise -user +
$PART + -partition +
$PWEXPIRES + -pwexpires +
$SERVER + -server +
$UID + -uid if provided; otherwise allocated by Protection +Server +
$USER + -user +
$1 through $9 + -var +
+

To create an AFS account with the uss add command

Authenticate as an AFS identity with all of the following +privileges. In the conventional configuration, the admin +user account has them, or you possibly have a personal administrative +account. (To increase cell security, it is best to create special +privileged accounts for use only while performing administrative +procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog +command to authenticate. +
```
   % klog admin_user
+   Password: admin_password
+
```
+
The following list specifies the necessary privileges and indicates how to +check that you have them. +
- Membership in the system:administrators group. If +necessary, issue the pts membership command, which is fully +described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
  +
- Inclusion in the /usr/afs/etc/UserList file. If +necessary, issue the bos listusers command, which is fully +described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
  +
- The ADMIN flag on the Authentication Database entry. +However, the Authentication Server always prompts you for a password in order +to perform its own authentication. The following instructions direct +you to specify the administrative identity on the uss command line +itself. +
- The i (insert) and l (lookup) +permissions on the ACL of the directory in which you are mounting the +user's volume. If necessary, issue the fs listacl +command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
  +
  Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
+
(Optional) Log in as the local superuser +root. This is necessary only if you are creating new files +or directories in the local file system and want to designate an alternate +owner as the object is created. For a discussion of the issues +involved, see About Creating Local Disk Directories and Files. +
Verify the location and functionality of the template file you are +using. For a description of where the uss command +interpreter expects to find the template, see Where to Place Template Files. You can always provide an alternate pathname if you +wish. Also note the variables used in the template, to be sure that you +provide the corresponding arguments on the uss command line. +
(Optional) Change to the directory where the +template resides. This affects the type of pathname you must type in +Step 6. +
```
   % cd template_directory
+
```
+
(Optional) Run the uss add command with the +-dryrun flag to preview the creation of the account. Note +any error messages and correct the cause before reissuing the command without +the -dryrun flag. The next step describes the uss +add command's syntax. For more information on the +-dryrun flag, see Avoiding and Recovering from Errors and Interrupted Operations. + + +
Issue the uss add command to create the +account. Enter the command on a single line; it appears here on +multiple lines only for legibility. +
The uss add operation creates an Authentication Database +entry. The Authentication Server performs its own authentication rather +than accepting your existing AFS token. By default, it authenticates +your local (UNIX) identity, which possibly does not correspond to an +AFS-privileged administrator. Include the -admin argument to +name an identity that has the ADMIN flag on its Authentication +Database entry. To verify that an entry has the flag, issue the +kas examine command as described in To check if the ADMIN flag is set. +
```
   % uss add -user <login name>  -admin <administrator to authenticate>   \
+             [-realname <full name in quotes>] [-pass <initial passwd>]   \
+             [-pwexpires <password expires in [0..254] days (0 => never)>]  \
+             [-server <FileServer for home volume>]  \
+             [-partition <FileServer's disk partition for home volume>]  \
+             [-mount <home directory mount point>]  \
+             [-uid <uid to assign the user>]  \
+             [-template <pathname of template file>]  \
+             [-var <auxiliary argument pairs (Numval)>⁺] [-dryrun] \
+             [-overwrite] 
+   Administrator's (admin_user) password: admin_password
+
```
+
where +
+
ad +
Is the shortest acceptable abbreviation of add. +
-user +
Names the user's Authentication Database and Protection Database +entries. Because it becomes the username (the name under which a user +logs in), it must obey the restrictions that many operating systems impose on +usernames (usually, to contain no more than eight lowercase letters). +Also avoid the following characters: colon (:), +semicolon (;), comma (,), at sign (@), +space, newline, and the period (.), which is conventionally +used only in special administrative names. +
This argument provides the value for the $USER variable in the template +file. For suggestions on standardizing usernames, see Choosing Usernames and Naming Other Account Components. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
-realname +
Specifies the user's actual full name. If it contains spaces +or punctuation, surround it with double quotes. If you do not provide +it, it defaults to the username provided with the -user +argument. +
This argument provides the value for the $NAME variable in the template +file. For information about using this argument and variable as part of +an automated process for creating entries in a local password file such as +/etc/passwd, see Creating a Common Source Password File. +
-pass +
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. +
Possible choices for initial passwords include the username, a string of +digits such as those from a Social Security number, or a standard string such +as changeme, which is the default if you do not provide this +argument. There is no corresponding variable in the template +file. +
Instruct users to change their passwords to a truly secret string as soon +as they authenticate with AFS for the first time. The IBM AFS User +Guide explains how to use the kpasswd command to change an +AFS password. +
-pwexpires +
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 if you +do not provide this argument). 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. +
This argument provides the value for the $PWEXPIRES variable in the +template file. +
-server +
Names the file server machine on which to create the new user's home +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 when +you issue the uss add command. +
This argument provides the value for the $SERVER variable in the template +file. To avoid having to type a fully qualified hostname on the command +line, combine the $SERVER variable with a constant (for example, the +cell's domain name) in the server field of the V +instruction in the template file. For an example, see Creating a Volume with the V Instruction. +
-partition +
Specifies the partition on which to create the user's home +volume; it must be on the file server machine named by the +-server argument. Identify the partition by its complete +name (for example, /vicepa), or use one of the abbreviations listed +in Rules for Using Abbreviations and Aliases. +
This argument provides the value for the $PART variable in the template +file. +
-mount +
Specifies the pathname for the user's home directory in the +cell's read/write filespace. Partial pathnames are interpreted +relative to the current working directory. +
This argument provides the value for the $MTPT variable in the template +file, but only when it appears in the V instruction's +mount_point field. When the $MTPT variable appears in any +subsequent instructions, it takes its value from the V +instruction's mount_point field, rather than directly from this +argument. For more details, and for suggestions about how to use this +argument and the $MTPT variable, see Creating a Volume with the V Instruction. +
-uid +
Specifies a positive integer other than 0 (zero) to assign as +the user's AFS UID. It is best to omit this argument and allow the +Protection Server to assign an AFS UID that is one greater than the current +value of the max user id counter. (To display the counter, +use the pts listmax command as described in To display the AFS ID counters.) +
If you have a reason to use this argument (perhaps because the user already +has a UNIX UID), first use the pts examine command to verify that +there is no existing account with the desired AFS UID; if there is, the +account creation process terminates with an error. +
This argument provides the value for the $UID variable in the template +file. +
-template +
Specifies the pathname of the template file. If you omit this +argument, the command interpreter searches for a template file called +uss.template in each of the following directories in +turn: +
1. The current working directory +
2. /afs/cellname/common/uss, where +cellname names the local cell +
3. /etc +
+
If you specify a filename other than uss.template but +without a pathname, the command interpreter searches for it in the indicated +directories. If you provide a full or partial pathname, the command +interpreter consults the specified file only; it interprets partial +pathnames relative to the current working directory. +
If the specified template file is empty (zero-length), the command creates +Protection and Authentication Database entries only. +
To learn how to construct a template file, see Constructing a uss Template File. +
-var +
Specifies values for each of the number variables $1 through $9 that can +appear in the template file. You can use the number variables to assign +values to variables in the uss template file that are not part of +the standard set. +
For each instance of this argument, provide two parts in the indicated +order, separated by a space: +
- The integer from the range 1 through 9 that matches +the variable in the template file. Do not precede it with a dollar +sign. +
- A string of alphanumeric characters to assign as the value of the +variable. +
+
To learn about suggested uses for the number variables, see the description +of the V instruction's quota field in Creating a Volume with the V Instruction. +
-dryrun +
Reports actions that the command interpreter needs to perform to run the +command, without actually performing them. +
-overwrite +
Overwrites any directories, files, and links that exist in the file system +and for which there are definitions in D, E, +F, L, or S instructions in the template file +named by the -template argument. If you omit this flag, the +command interpreter prompts you once for confirmation that you want to +overwrite all such elements. +
+

If the new user home directory resides in a replicated volume, use the +vos release command to release the volume, as described in To replicate a read/write volume (create a read-only volume). +

   
+   % vos release <volume name or ID>
+   
+

Note:

This step can be necessary even if the home directory's parent directory +is not itself a mount point for a replicated volume (and is easier to overlook +in that case). For example, the ABC Corporation template puts the mount +points for user volumes in the /afs/abc.com/usr +directory. Because that is a regular directory rather than a mount +point, it resides in the root.cell volume mounted at the +/afs/abc.com directory. That volume is replicated, so +after changing it by creating a new mount point the administrator must issue +the vos release command. +

Create an entry for the new user in the local password file +(/etc/passwd or equivalent) on each AFS client machine that he or +she can log into. For suggestions on automating this step, see Creating a Common Source Password File. +
Even if you do not use the automated method, set the user's UNIX UID +to match the AFS UID assigned automatically by the Protection Server or +assigned with the -uid argument. The new user's AFS UID +appears in the trace produced by the uss add output, or you can use +the pts examine command to display it, as described in To display a Protection Database entry. +

+ + + + + + + +

Deleting Individual Accounts with the uss delete Command

The uss delete command deletes an AFS user +account according to the arguments you provide on the command line; +unlike the uss add command, it does not use a template file. +When you issue the command, the uss command interpreter contacts +various AFS servers to perform the following actions: +

Remove the mount point for the user's home volume +
Remove the user's home volume and delete the associated VLDB entry, +unless you include the -savevolume flag +
Delete the user's Authentication Database entry +
Delete the user's Protection Database entry +

Before issuing the uss delete command, you can also perform the +following optional tasks: +

Copy the user's home volume to tape or another permanent medium and +record the username and UID on a reserved list. This information +enables you to restore the user's account easily if he or she returns to +your cell. For information about using the AFS Backup System to back up +volumes, see Configuring the AFS Backup System and Backing Up and Restoring AFS Data. +
If the user has exclusive use of any other volumes (such as a volume for +storing project-related data), make a backup copy of each one and then remove +it and its mount point as instructed in Removing Volumes and their Mount Points. +
Use the pts listowned command to display any groups that the +user owns; instructions appear in To list the groups that a user or group owns. Decide whether to use the pts delete +command to remove the groups or the pts chown command to transfer +ownership to another user or group. Instructions appear in To delete Protection Database entries and To change a group's owner. Alternatively, you can have the +user remove or transfer ownership of the groups before leaving. A group +that remains in the Protection Database after its owner is removed is +considered orphaned, and only members of the +system:administrators group can administer it. +

You can automate some of these tasks by including exec +instructions in the bulk input file and using the uss bulk command +to delete the account. See Creating and Deleting Multiple Accounts with the uss bulk Command. +

To delete an AFS account

Authenticate as an AFS identity with all of the following +privileges. In the conventional configuration, the admin +user account has them, or you possibly have a personal administrative +account. (To increase cell security, it is best to create special +privileged accounts for use only while performing administrative +procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog +command to authenticate. +
```
   % klog admin_user
+   Password: admin_password
+
```
+
The following list specifies the necessary privileges and indicates how to +check that you have them. +
- Membership in the system:administrators group. If +necessary, issue the pts membership command, which is fully +described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
  +
- Inclusion in the /usr/afs/etc/UserList file. If +necessary, issue the bos listusers command, which is fully +described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
  +
- The ADMIN flag on the Authentication Database entry. +However, the Authentication Server always prompts you for a password in order +to perform its own authentication. The following instructions direct +you to specify the administrative identity on the uss command line +itself. +
- The d (delete) permission on the ACL of the +directory that houses the user's home directory. If necessary, +issue the fs listacl command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
  +
  Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
+
Consider and resolve the issues discussed in the introduction to this +section concerning the continued maintenance of a deleted user's account +information, owned groups, and volumes. +
(Optional) Run the uss delete command with the +-dryrun flag to preview the deletion of the account. Note +any error messages and correct the cause before reissuing the command without +the -dryrun flag. The next step describes the uss +delete command's syntax. + + +
Issue the uss delete command to delete the account. +Enter the command on a single line; it appears here on multiple lines +only for legibility. +
The delete operation always removes the user's entry from the +Authentication Database. The Authentication Server performs its own +authentication rather than accepting your existing AFS token. By +default, it authenticates your local (UNIX) identity, which possibly does not +correspond to an AFS-privileged administrator. Include the +-admin argument to name an identity that has the ADMIN +flag on its Authentication Database entry. To verify that an entry has +the flag, issue the kas examine command as described in To check if the ADMIN flag is set. +
```
   % uss delete -user <login name>  \ 
+                -mountpoint <mountpoint for user's volume>  \
+                [-savevolume]  -admin  <administrator to authenticate>  \
+                [-dryrun] 
+   Administrator's (admin_user) password: admin_password
+
```
+
where +
+
d +
Is the shortest acceptable abbreviation of delete. +
-user +
Names the entry to delete from the Protection and Authentication +Databases. +
-mountpoint +
Specifies the pathname of the mount point to delete (the user's home +directory). Unless the -savevolume argument is included, the +volume mounted there is also deleted from the file server machine where it +resides, as is its record from the VLDB. Partial pathnames are +interpreted relative to the current working directory. +
Specify the read/write path to the mount point, to avoid the failure that +results when you attempt to delete a mount point from a read-only +volume. By convention, you indicate the read/write path 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 Mounting Volumes. +
-savevolume +
Retains the user's volume and VLDB entry. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
-dryrun +
Reports actions that the command interpreter needs to perform to run the +command, without actually performing them. +
+

If the deleted user home directory resided in a replicated volume, use the +vos release command to release the volume, as described in To replicate a read/write volume (create a read-only volume). +

   
+   % vos release <volume name or ID>
+   
+

Note:

This step can be necessary even if the home directory's parent directory +is not itself a mount point for a replicated volume (and is easier to overlook +in that case). For example, the ABC Corporation template puts the mount +points for user volumes in the /afs/abc.com/usr +directory. Because that is a regular directory rather than a mount +point, it resides in the root.cell volume mounted at the +/afs/abc.com directory. That volume is replicated, so +after changing it by deleting a mount point the administrator must issue the +vos release command. +

Delete the user's entry from the local password file +(/etc/passwd or equivalent) of each client machine. If you +use the AFS package utility, it is sufficient to remove the entry +from the common source version of the file. If you intend to reactivate +the user's account in the future, it is simpler to comment out the entry +or place an asterisk (*) in the password field. +

+ + + + + +

Creating and Deleting Multiple Accounts with the uss bulk Command

The uss bulk command allows you to create and +delete many accounts at once. Before executing the command, you must +

Construct a template if you plan to create any accounts, just as you must +do before running the uss add command. The same template +applies to all accounts created by a single uss bulk +command. +
Construct a bulk input file of instructions that create and delete +accounts and execute any related commands, as described in Constructing a Bulk Input File. +

+ + +

Constructing a Bulk Input File

You can include five types of instructions in a bulk input +file: add, delete, exec, +savevolume, and delvolume. The following sections +discuss their uses. +

Creating a User Account with the add Instruction +

Each add instruction creates a single user account, and so is +basically the equivalent of issuing one uss add command. +There is no limit to the number of add instructions in the bulk +input file. +

As indicated by the following syntax statement, the order of the +instruction's fields matches the order of arguments to the uss +add command (though some of the command's arguments do not have a +corresponding field). Like the uss add command's +arguments, many of the fields provide a value for a variable in the +uss template file. Each instruction must be a single line in +the file (have a newline character only at its end); it appears on +multiple lines here only for legibility. +

   add username[:full_name][:initial_password][:password_expires]
+   [:file_server][:partition][:mount_point][:uid]
+   [:var1][:var2][:var3][:var4][:var5][:var6][:var7][:var8][:var9][:]
+

For a complete description of the acceptable values in each field, see the +uss Bulk Input File reference page in the IBM AFS +Administration Reference, or the description of the corresponding +arguments to the uss add command, in To create an AFS account with the uss add command. Following are some basic notes: +

Begin the line with the string add only, not uss +add. +
Only the first argument, username, is required. It +corresponds to the -user argument to the uss add +command. +
Do not surround the full_name value with double quotes, even +though you must use them around the value for the -realname +argument to the uss add command. +
If you want to omit a value for an argument, indicate an empty field by +using two colons with nothing between them. Leaving a field empty is +acceptable if the corresponding command line argument is optional or if the +corresponding variable does not appear in the template file. For every +field that precedes the last one to which you assign an actual value, you must +either provide a value or indicate an empty field. It is acceptable, +but not necessary, to indicate empty fields after the last one in which you +assign a value. +
After the last field, end the line with either a colon and newline +character (<Return>), or a newline alone. +
The final nine fields are for assigning values to the number variables ($1 +through $9), with the fields listed in increasing numerical order. +Specify the value only, not the variable number. +

Deleting a User Account with the delete Instruction +

Each delete instruction deletes a single user account, and so is +basically the equivalent of issuing one uss delete command. +There is no limit to the number of delete instructions in the bulk +input file. +

Like all instructions in the bulk input file, each delete +instruction must be a single line in the file (have a newline character only +at its end), even though it can cover multiple lines on a display +screen. The curly braces ({ }) indicate two mutually +exclusive choices. +

   delete username:mount_point_path[:{ savevolume | delvolume }][:]
+

For a complete description of the acceptable values in each field, see the +uss Bulk Input File reference page in the IBM AFS +Administration Reference or the description of the corresponding +arguments to the uss delete command, in To delete an AFS account. Following are some basic notes: +

Begin the line with the string delete only, not uss +delete. +
The first two arguments, username and mount_point_path, +are required. They correspond to the -user and +-mountpoint arguments to the uss delete command. +
The third field, which is optional, controls whether the user's home +volume is removed from the file server where it resides, along with the +corresponding VLDB entry. There are three possible values: +
- No value treats the volume and VLDB entry according to the prevailing +default, which is established by a preceding savevolume or +delvolume instruction in the template file. See the +following discussion of those instructions to learn how the default is +set. +
- The string savevolume preserves the volume and VLDB entry, +overriding the default. +
- The string delvolume removes the volume and VLDB entry, +overriding the default. +
+
After the last field, end the line with either a colon and newline +character (<Return>), or a newline alone. +

Running a Command or Script with the exec Instruction +

The exec instruction runs the indicated AFS command, compiled +program, or UNIX shell script or command. The command processor assumes +the AFS and local identities of the issuer of the uss bulk command, +who must have the privileges required to run the command. +

The instruction's syntax is as follows: +

   exec command
+

It is not necessary to surround the command string with double +quotes (" ") or other delimiters. +

Setting the Default Treatment of Volumes with the delvolume and +savevolume Instructions +

The savevolume and delvolume instructions set 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
+

Both instructions are optional and take no arguments. If neither +appears in the bulk input file, then by default all volumes and VLDB entries +referenced by delete instructions are removed. If the +savevolume instruction appears in the file, it prevents the removal +of the volume and VLDB entry referenced by all subsequent delete +instructions in the file. The delvolume instruction +explicitly establishes the default (which is deletion) for subsequent +delete instructions. +

The effect of either instruction lasts until the end of the bulk input +file, or until its opposite appears. To override the prevailing default +for a particular delete instruction, put the savevolume +or delvolume string in the instruction's third field. +(You can also use multiple instances of the savevolume and +delvolume instructions to toggle back and forth between default +preservation and deletion of volumes.) +

Example Bulk Input File Instructions

To create an authentication-only account, use an add +instruction like the following example, which includes only the first +(username) argument. The user's real name is set to match +the username (anderson) and her initial password is set to the +string changeme. +

   add anderson 
+

The following example also creates an authentication-only account, but sets +nondefault values for the real name and initial password. +

   add smith:John Smith:js_pswd
+

The next two example add instructions require that the +administrator of the ABC Corporation cell (abc.com) has +written a uss template file with the following V +instruction in it: +

   V user.$USER $SERVER.abc.com /vicep$PART 10000 /afs/.abc.com/usr/$3/$USER \
+       $UID $USER all
+

To create accounts for users named John Smith from the Marketing Department +and Pat Jones from the Finance Department, the appropriate add +instructions in the bulk input file are as follows: +

   add smith:John Smith:::fs1:a:::::marketing
+   add jones:Pat Jones:::fs3:c:::::finance
+

The new account for Smith consists of Protection and Authentication +Database entries called smith. His initial password is the +default string changeme, and the Protection Server generates his +AFS UID. His home volume, called user.smith, has a +10,000 KB quota, resides on partition /vicepa of file server +machine fs1.abc.com, and is mounted at +/afs/.abc.com/usr/marketing/smith. The final +$UID $USER all part of the V instruction gives him +ownership of his home directory and all permissions on its ACL. The +account for jones is similar, except that it 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 mount_point, uid, +var1, and var2 are empty (between the values a +and marketing on the first example line) because the corresponding +variables do not appear in the V instruction in the template +file. The initial_passwd and password_expires fields +are also empty. +

If you wish, you can specify values or empty fields for all nine number +variables in an add instruction. In that case, the bulk +input file instructions are as follows: +

   add smith:John Smith:::fs1:a:::::marketing::::::
+   add jones:Pat Jones:::fs3:c:::::finance::::::
+

The following example is a section of a bulk input file with a number of +delete instructions and a savevolume instruction. +Because the first three instructions appear before the savevolume +instruction and their third field is blank, the corresponding volumes and VLDB +entries are removed. The delete instruction for user +terry follows the savevolume instruction, so her volume +is not removed, but the volume for user johnson is, because the +delvolume string in the third field of the 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 is useful as a separator +between a set of add instructions and a set of delete +instructions. It generates a message on the standard output stream that +informs you of the uss bulk command's progress. +

   exec echo "Additions completed; beginning deletions..."
+

To create and delete multiple AFS user accounts

Authenticate as an AFS identity with all of the following +privileges. In the conventional configuration, the admin +user account has them, or you possibly have a personal administrative +account. (To increase cell security, it is best to create special +privileged accounts for use only while performing administrative +procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog +command to authenticate. +
```
   % klog admin_user
+   Password: admin_password
+
```
+
The following list specifies the necessary privileges and indicates how to +check that you have them. +
- Membership in the system:administrators group. If +necessary, issue the pts membership command, which is fully +described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
  +
- Inclusion in the /usr/afs/etc/UserList file. If +necessary, issue the bos listusers command, which is fully +described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
  +
- The ADMIN flag on the Authentication Database entry. +However, the Authentication Server always prompts you for a password in order +to perform its own authentication. The following instructions direct +you to specify the administrative identity on the uss command line +itself. +
- The d (delete), i (insert) and +l (lookup) permissions on the ACL of the parent +directory for each volume mount point. If necessary, issue the fs +listacl command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
  +
  Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
+
(Optional.) Log in as the local superuser +root. This is necessary only if you are creating new files +or directories in the local file system and want to designate an alternate +owner as the object is created. For a discussion of the issues +involved, see About Creating Local Disk Directories and Files. +
If the bulk input file includes add instructions, verify the +location and functionality of the template you are using. For a +description of where the uss command interpreter expects to find +the template, see Where to Place Template Files. You can always provide an alternate pathname if you +wish. Also note which variables appear in the template, to be sure that +you provide the corresponding arguments in the add instruction or +on the uss bulk command line. +
Create a bulk input file that complies with the rules listed in Constructing a Bulk Input File. It is simplest to put the file in the same directory +as the template file you are using. +
(Optional.) Change to the directory where the bulk input +file and template file reside. +
```
   % cd template_directory
+
```
+ + +
Issue the uss bulk command to create or delete +accounts, or both. Enter the command on a single line; it appears +here on multiple lines only for legibility. +
The bulk operation always manipulates user entries in the Authentication +Database. The Authentication Server performs its own authentication +rather than accepting your existing AFS token. By default, it +authenticates your local (UNIX) identity, which possibly does not correspond +to an AFS-privileged administrator. Include the -admin +argument to name an identity that has the ADMIN flag on its +Authentication Database entry. To verify that an entry has the flag, +issue the kas examine command as described in To check if the ADMIN flag is set. +
```
   % uss bulk <bulk input file>  \
+              [-template <pathname of template file>]  \
+              -admin <administrator to authenticate>  \
+              [-dryrun] [-overwrite]  \
+              [-pwexpires <password expires in [0..254] days (0 => never)>]  \
+              [-pipe]
+   Administrator's (admin_user) password: admin_password
+
```
+
where +
+
b +
Is the shortest acceptable abbreviation of bulk. +
bulk input file +
Specifies the pathname of the bulk input file. Partial pathnames +are interpreted relative to the current working directory. For a +discussion of the required file format, see Constructing a Bulk Input File. +
-template +
Specifies the pathname of the template file for any uss add +commands that appear in the bulk input file. Partial pathnames are +interpreted relative to the current working directory. For a discussion +of the required file format, see Constructing a uss Template File. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as the admin account. +The password prompt echoes it as admin_user. Enter the +appropriate password as admin_password. +
-dryrun +
Reports actions that the command interpreter needs to perform to run the +command, without actually performing them. +
-overwrite +
Overwrites any directories, files and links that exist in the file system +and for which there are also D, E, F, +L, or S instructions in the template file named by the +-template argument. If this flag is omitted, the command +interpreter prompts, once for each add instruction in the bulk +input file, for confirmation that it is to overwrite such elements. Do +not include this flag if there are no add instructions in the bulk +input file. +
-pwexpires +
Sets the number of days after a user's password is changed that it +remains valid, for each user named by an add instruction in the +bulk input file. 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). +
-pipe +
Suppresses the Authentication Server's prompt for the password of the +issuer or the user named by the -admin argument (the Authentication +Server always separately authenticates the user who is creating or deleting an +entry in the Authentication Database). Instead, the command interpreter +accepts the password as piped input from another program, enabling you to run +the uss bulk command in unattended batch jobs. +
+

If a newly created or deleted user home directory resides in a replicated +volume, use the vos release command to release the volume, as +described in To replicate a read/write volume (create a read-only volume). +

   
+   % vos release <volume name or ID>
+   
+

Note:

This step can be necessary even if the home directory's parent directory +is not itself a mount point for a replicated volume (and is easier to overlook +in that case). For example, the ABC Corporation template puts the mount +points for user volumes in the /afs/abc.com/usr +directory. Because that is a regular directory rather than a mount +point, it resides in the root.cell volume mounted at the +/afs/abc.com directory. That volume is replicated, so +after changing it by creating or deleting a mount point, the administrator +must issue the vos release command. +

If you are creating accounts, create an entry for the new user in the +local password file (/etc/passwd or equivalent) on each AFS client +machine that he or she can log into. For suggestions on automating this +step, see Creating a Common Source Password File. +
Even if you do not use the automated method, set the user's UNIX UID +to match the AFS UID assigned automatically by the Protection Server or +assigned with the -uid argument. The new user's AFS UID +appears in the trace produced by the uss add output or you can use +the pts examine command to display it, as described in To display a Protection Database entry. +
If you are deleting accounts, delete the user's entry from the local +password file (/etc/passwd or equivalent) of each client +machine. If you use the AFS package utility, it is +sufficient to remove the entry from the common source version of the +file. If you intend to reactivate the user's account in the +future, it is simpler to comment out the entry or place an asterisk (*) in the +password field. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd018.htm b/doc/html/AdminGuide/auagd018.htm new file mode 100644 index 0000000..fa92fe5 --- /dev/null +++ b/doc/html/AdminGuide/auagd018.htm @@ -0,0 +1,1391 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

+ +

Administering User Accounts

This chapter explains how to create and maintain user +accounts in your cell. +

The preferred method for creating user accounts is the uss +program, which enables you to create multiple accounts with a single +command. See Creating and Deleting User Accounts with the uss Command Suite. If you prefer to create each account +component individually, follow the instructions in Creating AFS User Accounts. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + + + + + + + + + + + + + +
Create Protection Database entry + pts createuser +
Create Authentication Database entry + kas create +
Create volume + vos create +
Mount volume + fs mkmount +
Create entry on ACL + fs setacl +
Examine Protection Database entry + pts examine +
Change directory ownership + /etc/chown +
Limit failed authentication attempts + kas setfields with -attempts and +-locktime +
Unlock Authentication Database entry + kas unlock +
Set password lifetime + kas setfields with -pwexpires +
Prohibit password reuse + kas setfields with -reuse +
Change AFS password + kas setpassword +
List groups owned by user + pts listowned +
Rename Protection Database entry + pts rename +
Delete Authentication Database entry + kas delete +
Rename volume + vos rename +
Remove mount point + fs rmmount +
Delete Protection Database entry + pts delete +
List volume location + vos listvldb +
Remove volume + vos remove +
+

+ +

The Components of an AFS User Account

The differences between AFS and the UNIX file system imply +that a complete AFS user account is not the same as a UNIX user +account. The following list describes the components of an AFS +account. The same information appears in a corresponding section of Creating and Deleting User Accounts with the uss Command Suite, but is repeated here for your convenience. +

A Protection Database entry defines the username (the name +provided when authenticating with AFS), and maps it to an AFS user ID (AFS +UID), a number that the AFS servers use internally when referencing +users. The Protection Database also tracks the groups to which the user +belongs. For details, see Administering the Protection Database. +
An Authentication Database entry records the user's AFS +password in a scrambled form suitable for use as an encryption key. +
A home volume stores all the files in the user's home +directory together on a single partition of a file server machine. The +volume has an associated quota that limits its size. For a +complete discussion of volumes, see Managing Volumes. +
A mount point makes the contents of the user's volume +visible and accessible in the AFS filespace, and acts as the user's home +directory. For more details about mount points, see About Mounting Volumes. +
Full access permissions on the home directory's access control +list (ACL) and ownership of the directory (as displayed by the UNIX +ls -ld command) enable the user to manage his or her files. +For details on AFS file protection, see Managing Access Control Lists. +
A local password file entry (in the /etc/passwd file +or equivalent) of each AFS client machine enables the user to log in and +access AFS files through the Cache Manager. A subsequent section in +this chapter further discusses local password file entries. +
Other optional configuration files make the account more +convenient to use. Such files help the user log in and log out more +easily, receive electronic mail, print, and so on. +

+ + +

Creating Local Password File Entries

To obtain authenticated access to a cell's AFS +filespace, a user must not only have a valid AFS token, but also an entry in +the local password file (/etc/passwd or equivalent) of the machine +whose Cache Manager is representing the user. This section discusses +why it is important for the user's AFS UID to match to the UNIX UID +listed in the local password file, and describes the appropriate value to put +in the file's password field. +

One reason to use uss commands is that they enable you to +generate local password file entries automatically as part of account +creation. See Creating a Common Source Password File. +

Information similar to the information in this section appears in a +corresponding section of Creating and Deleting User Accounts with the uss Command Suite, but is repeated here for your convenience +

Assigning AFS and UNIX UIDs that Match

A user account is easiest to administer and use if the AFS +user ID number (AFS UID) and UNIX UID match. All instructions in the +AFS documentation assume that they do. +

Follow the recommendations in the indicated sections to make AFS and UNIX +UIDs match when creating accounts for various types of users: +

If creating an AFS account for a user who already has a UNIX UID, see Making UNIX and AFS UIDs Match. +
If some users in your cell have existing UNIX accounts but the user for +whom you are creating an AFS account does not, then it is best to allow the +Protection Server to allocate an AFS UID automatically. To avoid +overlap of AFS UIDs with existing UNIX UIDs, set the Protection +Database's max user id counter higher than the largest UNIX +UID, using the instructions in Displaying and Setting the AFS UID and GID Counters. +
If none of your users have existing UNIX accounts, allow the Protection +Server to allocate AFS UIDs automatically, starting either at its default or +at the value you have set for the max user id counter. +

+ + +

Specifying Passwords in the Local Password File

To prevent both local login and AFS authentication, place an asterisk ( * +) in the field. This is useful mainly in emergencies, when you want to +prevent a certain user from logging into the machine. +
To prevent login to the local file system if the user does not provide the +correct AFS password, place a character string of any length other than the +standard thirteen characters in the field. This is appropriate if you +want to allow only people with local AFS accounts to log into to your +machines. A single X or other character is the most easily +recognizable way to do this. +
To enable a user to log into the local file system even after providing an +incorrect AFS password, record a standard UNIX encrypted password in the field +by issuing the standard UNIX password-setting command (passwd or +equivalent). +

Converting Existing UNIX Accounts

This section discusses the three main issues you need to +consider if your cell has existing UNIX accounts that you wish to convert to +AFS accounts. +

Making UNIX and AFS UIDs Match

Make the AFS UIDs match the existing UNIX UIDs. In this case, you +need to assign the AFS UID yourself by including the -id argument +to the pts createuser command as you create the AFS account. +
+
Because you are retaining the user's UNIX UID, you do not need to +alter the UID in the local password file entry. However, if you are +using an AFS-modified login utility, you possibly need to change the password +field in the entry. For a discussion of how the value in the password +field affects login with an AFS-modified login utility, see Specifying Passwords in the Local Password File. +
If now or in the future you need to create AFS accounts for users who do +not have an existing UNIX UID, then you must guarantee that new AFS UIDs do +not conflict with any existing UNIX UIDs. The simplest way is to set +the max user id counter in the Protection Database to a value +higher than the largest existing UNIX UID. See Displaying and Setting the AFS UID and GID Counters. +
Change the existing UNIX UIDs to match the new AFS UIDs that the +Protection Server assigns automatically. +
Allow the Protection Server to allocate the AFS UIDs automatically as you +create AFS accounts. You must then alter the user's entry in the +local password file on every client machine to include the new UID. +
There is one drawback to changing the UNIX UID: any files and +directories that the user owned in the local file system before becoming an +AFS user still have the former UID in their owner field. If you want +the ls -l and ls -ld commands to display the correct +owner, you must use the chown command to change the value to the +user's new UID, whether you are leaving the file in the local file system +or moving it to AFS. See Moving Local Files into AFS. +

Setting the Password Field Appropriately

If the login utility is not modified for use with AFS, the actual password +must appear (in scrambled form) in the local password file entry. +
If the login utility is modified for use with AFS, choose one of the +values discussed in Specifying Passwords in the Local Password File. +

Moving Local Files into AFS

Creating AFS User Accounts

There are two methods for creating user accounts. The +preferred method--using the uss commands--enables you to +create multiple accounts with a single command. It uses a template to +define standard values for the account components that are the same for each +user (such as quota), but provide differing values for more variable +components (such as username). See Creating and Deleting User Accounts with the uss Command Suite. +

The second method involves issuing a separate command to create each +component of the account. It is best suited to creation of one account +at a time, since some of the commands can create only one instance of the +relevant component. To review the function of each component, see The Components of an AFS User Account. +

Use the following instructions to create any of the three types of user +account, which differ in their levels of functionality. For a +description of the types, see Configuring AFS User Accounts. +

To create an authentication-only account, perform Step 1 through Step 4 and also Step 14. This type of +account consists only of entries in the Authentication Database and Protection +Database. +
To create a basic account, perform Step 1 through Step 8 and Step 11 through Step 14. +In addition to Authentication Database and Protection Database entries, this +type of account includes a volume mounted at the home directory with owner and +ACL set appropriately. +
To create a full account, perform all steps in the following +instructions. This type of account includes configuration files for +basic functions such as logging in, printing, and mail delivery, making it +more convenient and useful. For a discussion of some useful types of +configuration files, see Creating Standard Files in New AFS Accounts. +

+ + + + + + + + + + +

To create one user account with individual commands

Decide on the value to assign to each of the following account +components. If you are creating an authentication-only account, you +need to pick only a username, AFS UID, and initial password. +
- The username. By convention, the names of many components of the +user account incorporate this name. For a discussion of restrictions +and suggested naming schemes, see Choosing Usernames and Naming Other Account Components. +
- The AFS UID, if you want to assign a specific one. It is generally +best to have the Protection Server allocate one instead, except when you are +creating an AFS account for a user who already has an existing UNIX +account. In that case, migrating the user's files into AFS is +simplest if you set the AFS UID to match the existing UNIX UID. See Converting Existing UNIX Accounts. +
- The initial password. Advise the user to change this at the first +login, using the password changing instructions in the IBM AFS User +Guide. +
- The name of the user's home volume. The conventional name is +user.username (for example, +user.smith). +
- The volume's site (disk partition on a file server machine). +Some cells designate certain machines or partitions for user volumes only, or +it possibly makes sense to place the volume on the emptiest partition that +meets your other criteria. To display the size and available space on a +partition, use the vos partinfo command, which is fully described +in Creating Read/write Volumes. +
- The name of the user's home directory (the mount point for the home +volume). The conventional location is a directory (or one of a set of +directories) directly under the cell directory, such as +/afs/cellname/usr. For suggestions on +how to avoid the slowed directory lookup that can result from having large +numbers of user home directories in a single usr directory, see Evenly Distributing User Home Directories with the G Instruction. +
- The volume's space quota. Include the -maxquota +argument to the vos create command, or accept the default quota of +5000 KB. +
- The ACL on the home directory. By default, the ACL on every new +volume grants all seven permissions to the +system:administrators group. After volume creation, +use the fs setacl command to remove the entry if desired, and to +grant all seven permissions to the user. +
+
Authenticate as an AFS identity with all of the following +privileges. In the conventional configuration, the admin +user account has them, or you possibly have a personal administrative +account. (To increase cell security, it is best to create special +privileged accounts for use only while performing administrative +procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog +command to authenticate. +
```
   % klog admin_user
+   Password: admin_password
+
```
+
The following list specifies the necessary privileges and indicates how to +check that you have them. +
- Membership in the system:administrators group. If +necessary, issue the pts membership command, which is fully +described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
  +
- Inclusion in the /usr/afs/etc/UserList file. If +necessary, issue the bos listusers command, which is fully +described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
  +
- The ADMIN flag on your Authentication Database entry. +However, the Authentication Server performs its own authentication, so in Step +4 you specify an administrative identity on the kas +command line itself. +
- The i (insert) and a +(administer) permissions on the ACL of the directory where you are +mounting the user's volume. If necessary, issue the fs +listacl command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
  +
  Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
- Knowledge of the password for the local superuser root. +
+ + +
Issue the pts createuser command to create an entry +in the Protection Database. For a discussion of setting AFS UIDs, see Assigning AFS and UNIX UIDs that Match. If you are converting an existing UNIX account into +an AFS account, also see Converting Existing UNIX Accounts. +
```
   % pts createuser <user name> [<user id>]
+
```
+
where +
+
cu +
Is an acceptable alias for createuser (and createu +is the shortest acceptable abbreviation). +
user name +
Specifies the user's username (the character string typed at +login). It is best to limit the name to eight or fewer lowercase +letters, because many application programs impose that limit. The AFS +servers themselves accept names of up to 63 lowercase letters. Also +avoid the following characters: colon (:), semicolon +(;), comma (,), at sign (@), space, +newline, and the period (.), which is conventionally used +only in special administrative names. +
user id +
Is optional and appropriate only if the user already has a UNIX UID that +the AFS UID must match. If you do not provide this argument, the +Protection Server assigns one automatically based on the counter described in Displaying and Setting the AFS UID and GID Counters. If the ID you specify is less than 1 +(one) or is already in use, an error results. +
+ + +
Issue the kas create command to create an entry in +the Authentication Database. To avoid having the user's temporary +initial password echo visibly on the screen, omit the +-initial_password argument; instead enter the password at the +prompts that appear when you omit the argument, as shown in the following +syntax specification. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas create <name of user> \
+                -admin  <admin principal to use for authentication>  
+   Administrator's (admin_user) password: admin_password
+   initial_password: initial_password
+   Verifying, please re-enter initial_password: initial_password
+
```
+
where +
+
cr +
Is the shortest acceptable abbreviation for create. +
name of user +
Specifies the same username as in Step 3. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
initial_password +
Specifies the initial password as a string of eight characters or less, to +comply with the length restriction that some applications impose. +Possible choices for an initial password include the username, a string of +digits from a personal identification number such as the Social Security +number, or a standard string such as changeme. Instruct the +user to change the string to a truly secret password as soon as possible by +using the kpasswd command as described in the IBM AFS User +Guide. +
+ + +
Issue the vos create command to create the +user's volume. +
```
   % vos create <machine name> <partition name> <volume name>  \
+                [-maxquota <initial quota (KB)>]
+
```
+
where +
+
cr +
Is the shortest acceptable abbreviation of create. +
machine name +
Names the file server machine on which to place the new volume. +
partition name +
Names the partition on which to place the new volume. +
volume name +
Names the new volume. The name can include up to 22 +characters. By convention, user volume names have the form +user.username, where username is the name +assigned in Step 3. +
-maxquota +
Sets the volume's quota, as a number of kilobyte blocks. If +you omit this argument, the default is 5000 KB. +
+ + +
Issue the fs mkmount command to mount the volume in +the filespace and create the user's home directory. +
```
   % fs mkmount <directory> <volume name>
+
```
+
where +
+
mk +
Is the shortest acceptable abbreviation for mkmount. +
directory +
Names the mount point to create. A directory of the same name must +not already exist. Partial pathnames are interpreted relative to the +current working directory. By convention, user home directories are +mounted in a directory called something like +/afs/.cellname/usr, and the home +directory name matches the username assigned in Step 3. +
Specify the read/write path to the mount point, to avoid the failure that +results when you attempt to create the new mount point in a read-only +volume. By convention, you indicate the read/write path 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 Rules of Mount Point Traversal. +
volume name +
Is the name of the volume created in Step 5. +
+
(Optional) Issue the fs setvol command with the +-offlinemsg argument to record auxiliary information about the +volume in its volume header. For example, you can record who owns the +volume or where you have mounted it in the filespace. To display the +information, use the fs examine command. +
```
   % fs setvol <dir/file path> -offlinemsg <offline message>
+
```
+
where +
+
sv +
Is an acceptable alias for setvol (and setv the +shortest acceptable abbreviation). +
dir/file path +
Names the mount point of the volume with which to associate the +message. Partial pathnames are interpreted relative to the current +working directory. +
Specify the read/write path to the mount point, to avoid the failure that +results when you attempt to change a read-only volume. By convention, +you indicate the read/write path 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 Rules of Mount Point Traversal. +
-offlinemsg +
Specifies up to 128 characters of auxiliary information to record in the +volume header. +
+
Issue the fs setacl command to set the ACL on the +new home directory. At the least, create an entry that grants all +permissions to the user, as shown. +
You can also use the command to edit or remove the entry that the vos +create command automatically places on the ACL for a new volume's +root directory, which grants all permissions to the +system:administrators group. Keep in mind that even if +you remove the entry, the members of the group by default have implicit +a (administer) and by default l +(lookup) permissions on every ACL, and can grant themselves other +permissions as required. +
For detailed instructions for the fs setacl command, see Setting ACL Entries. +
```
   % fs setacl <directory> -acl <user name> all \
+               [system:administrators desired_permissions]
+
```
+
(Optional) Create configuration files and +subdirectories in the new home directory. Possibilities include +.login and .logout files, a +shell-initialization file such as .cshrc, files to help with +printing and mail delivery, and so on. +
If you are converting an existing UNIX account into an AFS account, you +possibly wish to move some files and directories into the user's new AFS +home directory. See Converting Existing UNIX Accounts. +
(Optional) In the new .login or shell +initialization file, define the user's $PATH environment variable to +include the directories where AFS binaries are kept (for example, the +/usr/afsws/bin and /usr/afsws/etc directories). +
In Step 12 and Step 14, you must know the user's AFS +UID. If you had the Protection Server assign it in Step 3, you probably do not know it. If necessary, issue +the pts examine command to display it. +
```
   % pts examine <user or group name or id>
+
```
+
where +
+
e +
Is the shortest acceptable abbreviation of examine. +
user or group name or id +
Is the username that you assigned in Step 3. +
+
The first line of the output displays the username and AFS UID. For +further discussion and an example of the output, see Displaying Information from the Protection Database. +
Designate the user as the owner of the home directory and any +files and subdirectories created or moved in Step 9. Specify the owner by the AFS UID you learned in Step +11 rather than by username. This is necessary for new +accounts because the user does not yet have an entry in your local +machine's password file (/etc/passwd or equivalent). If +you are converting an existing UNIX account, an entry possibly already exists, +but the UID is possibly incorrect. In that case, specifying a username +means that the corresponding (possibly incorrect) UID is recorded as the +owner. +
Some operating systems allow only the local superuser root to +issue the chown command. If necessary, issuing the +su command before the chown command. +
```
   % chown new_owner_ID  directory
+
```
+
where +
+
new_owner_ID +
Is the user's AFS UID, which you learned in Step 11. +
directory +
Names the home directory you created in Step 6, plus each subdirectory or file you created in Step 9. +
+

If the new user home directory resides in a replicated volume, use the +vos release command to release the volume, as described in To replicate a read/write volume (create a read-only volume). +

   
+   % vos release <volume name or ID>
+   
+

Note:

This step can be necessary even if the home directory's parent directory +is not itself a mount point for a replicated volume (and is easier to overlook +in that case). Suppose, for example, that the ABC Corporation puts the +mount points for user volumes in the /afs/abc.com/usr +directory. Because that is a regular directory rather than a mount +point, it resides in the root.cell volume mounted at the +/afs/abc.com directory. That volume is replicated, so +after changing it by creating a new mount point the administrator must issue +the vos release command. +

Create or modify an entry for the new user in the local +password file (/etc/passwd or equivalent) of each machine the user +can log onto. Remember to make the UNIX UID the same as the AFS UID you +learned in Step 11, and to fill the password field appropriately (for +instructions, see Specifying Passwords in the Local Password File). +
If you use the package utility to distribute a common version of +the password file to all client machines, then you need to make the change +only in the common version. See Configuring Client Machines with the package Program. +

+ + + + +

Improving Password and Authentication Security

AFS provides several optional features than can help to +protect your cell's filespace against unauthorized access. The +following list summarizes them, and instructions follow. +

Limit the number of consecutive failed login attempts. +
One of the most common ways for an unauthorized user to access your +filespace is to guess an authorized user's password. This method +of attack is most dangerous if the attacker can use many login processes in +parallel or use the RPC interfaces directly. +
To protect against this type of attack, use the -attempts +argument to the kas setfields command to limit the number of times +that a user can consecutively fail to enter the correct password when using +either an AFS-modified login utility or the klog command. +When the limit is exceeded, the Authentication Server locks the user's +Authentication Database entry (disallows authentication attempts) for a period +of time that you define with the -locktime argument to the kas +setfields command. If desired, system administrators can use the +kas unlock command to unlock the entry before the complete lockout +time passes. +
In certain circumstances, the mechanism used to enforce the number of +failed authentication attempts can cause a lockout even though the number of +failed attempts is less than the limit set by the -attempts +argument. Client-side authentication programs such as klog +and an AFS-modified login utility normally choose an Authentication Server at +random for each authentication attempt, and in case of a failure are likely to +choose a different Authentication Server for the next attempt. The +Authentication Servers running on the various database server machines do not +communicate with each other about how many times a user has failed to provide +the correct password to them. Instead, each Authentication Server +maintains its own separate copy of the auxiliary database file +kaserverauxdb (located in the /usr/afs/local directory +by default), which records the number of consecutive authentication failures +for each user account and the time of the most recent failure. This +implementation means that on average each Authentication Server knows about +only a fraction of the total number of failed attempts. The only way to +avoid allowing more than the number of attempts set by the +-attempts argument is to have each Authentication Server allow only +some fraction of the total. More specifically, if the limit on failed +attempts is f, and the number of Authentication Servers is +S, then each Authentication Server can only permit a number of +attempts equal to f divided by S (the Ubik +synchronization site for the Authentication Server tracks any remainder, +fmodS). +
Normally, this implementation does not reduce the number of allowed +attempts to less than the configured limit (f). If one +Authentication Server refuses an attempt, the client contacts another instance +of the server, continuing until either it successfully authenticates or has +contacted all of the servers. However, if one or more of the +Authentication Server processes is unavailable, the limit is effectively +reduced by a percentage equal to the quantity U divided by +S, where U is the number of unavailable servers and +S is the number normally available. +
To avoid the undesirable consequences of setting a limit on failed +authentication attempts, note the following recommendations: +
- Do not set the -attempts argument (the limit on failed +authentication attempts) too low. A limit of nine failed attempts is +recommended for regular user accounts, to allow three failed attempts per +Authentication Server in a cell with three database server machines. +
- Set fairly short lockout times when including the -locktime +argument. Although guessing passwords is a common method of attack, it +is not a very sophisticated one. Setting a lockout time can help +discourage attackers, but excessively long times are likely to be more of a +burden to authorized users than to potential attackers. A lockout time +of 25 minutes is recommended for regular user accounts. +
- Do not assign an infinite lockout time on an account (by setting the +-locktime argument to 0 [zero]) unless there is a highly +compelling reason. Such accounts almost inevitably become locked at +some point, because each Authentication Server never resets the account's +failure counter in its copy of the kaauxdb file (in contrast, when +the lockout time is not infinite, the counter resets after the specified +amount of time has passed since the last failed attempt to that Authentication +Server). Furthermore, the only way to unlock an account with an +infinite lockout time is for an administrator to issue the kas +unlock command. It is especially dangerous to set an infinite +lockout time on an administrative account; if all administrative accounts +become locked, the only way to unlock them is to shut down all instances of +the Authentication Server and remove the kaauxdb file on +each. +
+
In summary, the recommended limit on authentication attempts is nine and +lockout time 25 minutes. +
Limit password lifetime. +
The longer a password is in use, the more time an attacker has to try to +learn it. To protect against this type of attack, use the +-pwexpires argument to the kas setfields command to +limit how many days a user's password is valid. The user becomes +unable to authenticate with AFS after the password expires, but has up to 30 +days to use the kpasswd command to set a new password. After +the 30 days pass, only an administrator who has the ADMIN flag on +the Authentication Database entry can change the password. +
If you set a password lifetime, many AFS-modified login utilities (but not +the klog command) set the PASSWORD_EXPIRES environment variable to +the number of days remaining until the password expires. A setting of +zero means that the password expires today. If desired, you can +customize your users' login scripts to display the number of days +remaining before expiration and even prompt for a password change when a small +number of days remain before expiration. +
Prohibit reuse of passwords. +
Forcing users to select new passwords periodically is not effective if they +simply set the new password to the current value. To prevent a user +from setting a new password to a string similar to any of the last 20 +passwords, use the -reuse argument to the kas setfields +command. +
If you prohibit password reuse and the user specifies an excessively +similar password, the Authentication Server generates the following message to +reject it: +
```
   Password was not changed because it seems like a reused password
+
```
+
A persistent user can try to bypass this restriction by changing the +password 20 times in quick succession (or running a script to do so). +If you believe this is likely to be a problem, you can include the +-minhours argument to the kaserver initialization +command (for details, see the command's reference page in the IBM +AFS Administration Reference. If the user attempts to change +passwords too frequently, the following message appears. +
```
   Password was not changed because you changed it too recently; see 
+   your systems administrator
+
```
+
Check the quality of new passwords. +
You can impose a minimum quality standard on passwords by writing a script +or program called kpwvalid. If the kpwvalid file +exists, the kpasswd and kas setpassword command +interpreters invoke it to check a new password. If the password does +not comply with the quality standard, the kpwvalid program returns +an appropriate code and the command interpreter rejects the password. +
The kpwvalid file must be executable, must reside in the same +AFS directory as the kpasswd and kas binaries, and its +directory's ACL must grant the w (write) permission +only to the system:administrators group. +
If you choose to write a kpwvalid program, consider imposing +standards such as the following. +
- A minimum length +
- Words found in the dictionary are prohibited +
- Numbers, punctuation, or both must appear along with letters +
+
The AFS distribution includes an example kpwvalid +program. See the kpwvalid reference page in the IBM AFS +Administration Reference. +

+ + +

To limit the number of consecutive failed authentication attempts

Issue the kas setfields command with the -attempts +and -locktime arguments. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas setfields <name of user>  \
+                   -admin <admin principal to use for authentication>  \
+                   -attempts <maximum successive failed login tries ([0..254])>  \
+                   -locktime <failure penalty [hh:mm or minutes]>
+   Administrator's (admin_user) password: admin_password
+
```
+
where +
+
name of user +
Names the Authentication Database entry to edit. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as the admin account. +The password prompt echoes it as admin_user. Enter the +appropriate password as admin_password. +
-attempts +
Specifies the maximum consecutive number of times that a user can fail to +provide the correct password during authentication (via the klog +command or an AFS-modified login utility) before the Authentication Server +refuses further attempts for the amount of time specified by the +-locktime argument. The range of valid values is +0 (zero) through 254. If you omit this argument +or specify 0, the Authentication Server allows an unlimited number +of failures. +
-locktime +
Specifies how long the Authentication Server refuses authentication +attempts after the user exceeds the failure limit specified by the +-attempts argument. +
Specify a time in either hours and minutes (hh:mm) +or minutes only (mm), from the range 01 (one minute) +through 36:00 (36 hours). The kas command +interpreter automatically reduces any larger value to 36:00 and also +rounds up each nonzero value to the next-higher multiple of 8.5 +minutes. +
It is best not to provide a value of 0 (zero), especially on +administrative accounts, because it sets an infinite lockout time. An +administrator must always issue the kas unlock command to unlock +such an account. +
+

To unlock a locked user account

Issue the kas command to enter interactive mode. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas -admin <admin principal to use for authentication>  
+   Administrator's (admin_user) password: admin_password
+   ka>
+
```
+
where -admin names an administrative account that has the +ADMIN flag on its Authentication Database entry, such as +admin. The password prompt echoes it as +admin_user. Enter the appropriate password as +admin_password. +
Issue the (kas) examine command to verify that the user's +account is in fact locked, as indicated by the message shown: +
```
   ka> examine <name of user>
+   User is locked until time
+
```
+ + +
Issue the (kas) unlock command to unlock the account. +
```
   ka> unlock <authentication ID> 
+
```
+
where +
+
u +
Is the shortest acceptable abbreviation of unlock. +
authentication ID +
Names the Authentication Database entry to unlock. +
+

+ + + +

To set password lifetime

Issue the kas setfields command with the -pwexpires +argument. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas setfields <name of user>  \
+                   -pwexpires <number days password is valid  [0..254])>  \
+                   -admin <admin principal to use for authentication> 
+   Administrator's (admin_user) password: admin_password
+
```
+
where +
+
name of user +
Specifies the Authentication Database entry on which to impose a password +expiration. +
-pwexpires +
Sets the number of days after the user's password was last changed +that it remains valid. Provide an integer from the range 1 +through 254 to specify the number of days until expiration. +
When the password becomes invalid (expires), the user is unable to +authenticate, but has 30 more days in which to issue the kpasswd or +kas setpassword command to change the password (after that, only an +administrator can change it). Note that the clock starts at the time +the password was last changed, not when the kas setfields command +is issued. To avoid retroactive expiration, have the user change the +password just before issuing the command. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
+

+ + +

To prohibit reuse of passwords

Issue the kas setfields command with the -reuse +argument. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas setfields <name of user> -reuse < permit password reuse (yes/no)>  \
+                   -admin <admin principal to use for authentication> 
+   Administrator's (admin_user) password: admin_password
+
```
+
where +
+
name of user +
Names the Authentication Database entry for which to set the password +reuse policy. +
-reuse +
Specifies whether the Authentication Server allows reuse of passwords +similar to any of the user's last 20 passwords. Specify the value +no to prohibit reuse, or the value yes to reinstate the +default of allowing password reuse. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
+

+ + + +

Changing AFS Passwords

After setting an initial password during account creation, +you normally do not need to change user passwords, since they can use the +kpasswd command themselves by following the instructions in the +IBM AFS User Guide. In the rare event that a user forgets +the password or otherwise cannot log in, you can use the kas +setpassword command to set a new password. +

If entries in the local password file (/etc/passwd or +equivalent) have actual scrambled passwords in their password field, remember +to change the password there also. For further discussion, see Specifying Passwords in the Local Password File. + + +

To change an AFS password

Issue the kas setpassword command to change the +password. To avoid having the new password echo visibly on the screen, +omit the -new_password argument; instead enter the password at +the prompts that appear when you omit the argument, as shown. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas setpassword <name of user>  \
+                     -admin <admin principal to use for authentication> 
+   Administrator's (admin_user) password: admin_password
+   new_password: new_password
+   Verifying, please re-enter new_password: new_password
+
```
+
where +
+
sp +
Is an acceptable alias for setpassword (setp is the +shortest acceptable abbreviation). +
name of user +
Names the Authentication Database entry for which to set the +password. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
new_password +
Specifies the user's new password. It is subject to the +restrictions imposed by the kpwvalid program, if you use it. +
+

Displaying and Setting the Quota on User Volumes

User volumes are like all other volumes with respect to +quota. Each new AFS volume has a default quota of 5000 KB, unless you +use the -maxquota argument to the vos create command to +set a different quota. You can also use either of the following +commands to change quota at any time: +

fs setquota +
fs setvol +

You can use any of the three following commands to display a volume's +quota: +

fs quota +
fs listquota +
fs examine +

For instructions, see Setting and Displaying Volume Quota and Current Size. + + + + + +

Changing Usernames

By convention, many components of a user account incorporate +the username, including the Protection and Authentication Database entries, +the volume name and the home directory name. When changing a username, +it is best to maintain consistency by changing the names of all components, so +the procedure for changing a username has almost as many steps as the +procedure for creating a new user account. +

To change a username

Authenticate as an AFS identity with all of the following +privileges. In the conventional configuration, the admin +user account has them, or you possibly have a personal administrative +account. (To increase cell security, it is best to create special +privileged accounts for use only while performing administrative +procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog +command to authenticate. +
```
   % klog admin_user
+   Password: admin_password
+
```
+
The following list specifies the necessary privileges and indicates how to +check that you have them. +
- Membership in the system:administrators group. If +necessary, issue the pts membership command, which is fully +described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
  +
- Inclusion in the /usr/afs/etc/UserList file. If +necessary, issue the bos listusers command, which is fully +described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
  +
- The ADMIN flag on the Authentication Database entry. +However, the Authentication Server performs its own authentication, so the +following instructions direct you to specify an administrative identity on the +kas command line itself. +
- The a (administer), d +(delete), and i (insert) permissions on the +ACL of the directory where you are removing the current mount point and +creating a new one. If necessary, issue the fs listacl +command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
  +
  Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
+
Issue the pts listowned command to display the names +of the groups the user owns. After you change the username in the +Protection Database in Step 3, you must issue the pts rename command to change +each group's owner prefix to match the new name, because the Protection +Server does not automatically make this change. For a complete +description of the pts listowned command, see Displaying Information from the Protection Database. +
```
   % pts listowned <user or group name or id>
+
```
+
Issue the pts rename command to change the +user's name in the Protection Database. +
```
   % pts rename <old name> <new name>
+
```
+
Issue the pts rename command to change the group names you +noted in Step 2, so that their owner prefix (the part of the group name +before the colon) accurately reflects the owner's new name. +
Repeat the command for each group. Step 3 details its syntax. +
```
   % pts rename <old name> <new name>
+
```
+
Issue the kas command to enter interactive mode. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas -admin <admin principal to use for authentication>  
+   Administrator's (admin_user) password: admin_password
+   ka>
+
```
+
where -admin names an administrative account that has the +ADMIN flag on its Authentication Database entry, such as +admin. The password prompt echoes it as +admin_user. Enter the appropriate password as +admin_password. + + +
Issue the (kas) delete command to delete the user's +existing Authentication Database entry. +
+
```
   ka> delete <name of user>
+
```
+
where +
+
del +
Is the shortest acceptable abbreviation for delete, or you can +use the alias rm. +
name of user +
Names the Authentication Database entry to delete. +
+ + +
Issue the (kas) create command to create an Authentication +Database entry for the new username. To avoid having the user's +password echo visibly on the screen, do not include the +-initial_password argument; instead enter the password at the +prompts that appear in that case, as shown in the following syntax +specification. +
```
   ka> create  <name of user>
+   initial_password: password
+   Verifying, please re-enter initial_password: password
+
```
+
where +
+
cr +
Is the shortest acceptable abbreviation for create. +
name of user +
Specifies the new username. +
password +
Specifies the password for the new user account. If the user is +willing to tell you his or her current password, you can retain it. +Otherwise, provide a string of eight characters or less to comply with the +length restriction that some applications impose. Possible choices for +an initial password include the username, a string of digits from a personal +identification number such as the Social Security number, or a standard string +such as changeme. Instruct the user to change the string to +a truly secret password as soon as possible by using the kpasswd +command as instructed in the IBM AFS User Guide. +
+
Issue the quit command to leave interactive mode. +
```
   ka> quit
+
```
+ + + + + +
Issue the vos rename command to change the name of +the user's volume. For complete syntax, see To rename a volume. +
```
   % vos rename  <old volume name>  <new volume name>
+
```
+ + + + + +
Issue the fs rmmount command to remove the existing +mount point. For the directory argument, specify the +read/write path to the mount point, to avoid the failure that results when you +attempt to delete a mount point from a read-only volume. +
```
   % fs rmmount <directory>
+
```
+ + + +
Issue the fs mkmount command to create a mount point +for the volume's new name. Specify the read/write path to the +mount point for the directory argument, as in the previous +step. For complete syntax, see Step 6 in To create one user account with individual commands. +
```
   % fs mkmount <directory> <volume name>
+
```
+

If the changes you made in Step 10 and Step 11 are to a mount point that resides in a +replicated volume, use the vos release command to release the +volume, as described in To replicate a read/write volume (create a read-only volume). +

   
+   % vos release <volume name or ID>
+   
+

Note:

This step can be necessary even if the home directory's parent directory +is not itself a mount point for a replicated volume (and is easier to overlook +in that case). For example, the ABC Corporation template puts the mount +points for user volumes in the /afs/abc.com/usr +directory. Because that is a regular directory rather than a mount +point, it resides in the root.cell volume mounted at the +/afs/abc.com directory. That volume is replicated, so +after changing it the administrator must issue the vos release +command. +

Removing a User Account

+ + +

Before removing an account, it is best to make a backup copy of the +user's home volume on a permanent storage medium such as tape. If +you need to remove several accounts, it is probably more efficient to use the +uss delete command instead; see Deleting Individual Accounts with the uss delete Command. +

To remove a user account

Authenticate as an AFS identity with all of the following +privileges. In the conventional configuration, the admin +user account has them, or you possibly have a personal administrative +account. (To increase cell security, it is best to create special +privileged accounts for use only while performing administrative +procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog +command to authenticate. +
```
   % klog admin_user
+   Password: admin_password
+
```
+
The following list specifies the necessary privileges and indicates how to +check that you have them. +
- Membership in the system:administrators group. If +necessary, issue the pts membership command, which is fully +described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
  +
- Inclusion in the /usr/afs/etc/UserList file. If +necessary, issue the bos listusers command, which is fully +described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
  +
- The ADMIN flag on the Authentication Database entry. +However, the Authentication Server performs its own authentication, so the +following instructions direct you to specify an administrative identity on the +kas command line itself. +
- The d (delete) permission on the ACL of the +directory where you are removing the user volume's mount point. If +necessary, issue the fs listacl command, which is fully described +in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
  +
  Members of the system:administrators group always +implicitly have the a (administer) and by default also +the l (lookup) permission on every ACL and can use the +fs setacl command to grant other rights as necessary. +
+
(Optional) If it is possible you need to restore the +user's account someday, note the username and AFS UID, possibly in a file +designated for that purpose. You can later restore the account with its +original AFS UID. +
(Optional) Copy the contents of the user's volume to +tape. You can use the vos dump command as described in Dumping and Restoring Volumes or the AFS Backup System as described in Backing Up Data. +
(Optional) If you intend to remove groups that the +user owns from the Protection Database after removing the user's entry, +issue the pts listowned command to display them. For +complete instructions, see Displaying Information from the Protection Database. +
```
   % pts listowned <user or group name or id>
+
```
+
(Optional) Issue the pts delete command +to remove the groups the user owns. However, if it is likely that other +users have placed the groups on the ACLs of directories they own, it is best +not to remove them. +
```
   % pts delete <user or group name or id>⁺
+
```
+
where +
+
del +
Is the shortest acceptable abbreviation for delete. +
user or group name or id +
Specifies the name or AFS UID of each group displayed in the output from +Step 4. +
+ + + +
Issue the kas delete command to remove the user's +Authentication Database entry. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
```
   % kas delete <name of user>  \
+                -admin  <admin principal to use for authentication>  
+   Administrator's (admin_user) password: admin_password
+
```
+
where +
+
d +
Is the shortest acceptable abbreviation for delete. +
name of user +
Names the Authentication Database entry to delete. +
-admin +
Names an administrative account that has the ADMIN flag on its +Authentication Database entry, such as admin. The password +prompt echoes it as admin_user. Enter the appropriate password +as admin_password. +
+
Issue the vos listvldb command to display the site +of the user's home volume in preparation for removing it. By +convention, user volumes are named +user.username. +
```
   % vos listvldb <volume name or ID>
+
```
+
where +
+
listvl +
Is the shortest acceptable abbreviation of listvldb. +
volume name or ID +
Specifies the volume's name or volume ID number. +
+ + + + +
Issue the vos remove command to remove the +user's volume. It automatically removes the backup version of the +volume, if it exists. It is not conventional to replicate user volumes, +so the command usually also completely removes the volume's entry from +the Volume Location Database (VLDB). If there are ReadOnly replicas of +the volume, you must repeat the vos remove command to remove each +one individually. +
```
   % vos remove <machine name> <partition name> <volume name or ID>
+
```
+
where +
+
remo +
Is the shortest acceptable abbreviation of remove. +
machine name +
Names the file server machine that houses the volume, as specified in the +output from Step 7. +
partition name +
Names the partition that houses the volume, as specified in the output +from Step 7. +
volume name or ID +
Specifies the volume's name or ID number. +
+ + + + +
Issue the fs rmmount command to remove the +volume's mount point. +
If you mounted the user's backup volume as a subdirectory of the home +directory, then this command is sufficient to unmount the backup version as +well. If you mounted the backup version at an unrelated location in the +filespace, repeat the fs rmmount command for it. +
```
   % fs rmmount <directory>
+
```
+
where +
+
rmm +
Is the shortest acceptable abbreviation of rmmount. +
directory +
Names the mount point for the volume's previous name (the former home +directory). Partial pathnames are interpreted relative to the current +working directory. +
Specify the read/write path to the mount point, to avoid the failure that +results when you attempt to delete a mount point from a read-only +volume. By convention, you indicate the read/write path 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 Mounting Volumes. +
+ + + + +
Issue the pts delete command to remove the +user's Protection Database entry. A complete description of this +command appears in Step 5. +
```
   % pts delete <user or group name or id>
+
```
+

   
+   % vos release <volume name or ID>
+   
+

Note:

This step can be necessary even if the home directory's parent directory +is not itself a mount point for a replicated volume (and is easier to overlook +in that case). For example, the ABC Corporation template puts the mount +points for user volumes in the /afs/abc.com/usr +directory. Because that is a regular directory rather than a mount +point, it resides in the root.cell volume mounted at the +/afs/abc.com directory. That volume is replicated, so +after changing it by deleting a mount point the administrator must issue the +vos release command. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd019.htm b/doc/html/AdminGuide/auagd019.htm new file mode 100644 index 0000000..e28b926 --- /dev/null +++ b/doc/html/AdminGuide/auagd019.htm @@ -0,0 +1,1437 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Administering the Protection Database

This chapter explains how to create and maintain user, +machine, and group entries in the Protection Database. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + + + + + + + + + + + + + + +
Display Protection Database entry + pts examine +
Map user, machine or group name to AFS ID + pts examine +
Display entry's owner or creator + pts examine +
Display number of users or machines belonging to group + pts examine +
Display number of groups user or machine belongs to + pts examine +
Display group-creation quota + pts examine +
Display entry's privacy flags + pts examine +
Display members of group, or groups that user or machine belongs to + pts membership +
Display groups that user or group owns + pts listowned +
Display all entries in Protection Database + pts listentries +
Create machine entry + pts createuser +
Create group entry + pts creategroup +
Add users and machines to groups + pts adduser +
Remove users and machines from groups + pts removeuser +
Delete machine or group entry + pts delete +
Change a group's owner + pts chown +
Change an entry's name + pts rename +
Set group creation quota + pts setfields +
Set entry's privacy flags + pts setfields +
Display AFS ID counters + pts listmax +
Set AFS ID counters + pts setmax +
+

+ + + + + + + + + + +

About the Protection Database

The Protection Database stores information about AFS users, +client machines, and groups which the File Server process uses to determine +whether clients are authorized to access AFS data. +

To obtain authenticated access to an AFS cell, a user must have an entry in +the cell's Protection Database. The first time that a user +requests access to the data stored on a file server machine, the File Server +on that machine contacts the Protection Server to request the user's +current protection subgroup (CPS), which lists all the +groups to which the user belongs. The File Server scans the access +control list (ACL) of the directory that houses the data, looking for groups +on the CPS. It grants access in accordance with the permissions that +the ACL extends to those groups or to the user individually. (The File +Server stores the CPS and uses it as long as the user has the same +tokens. When a user's group membership changes, he or she must +reauthenticate for the File Server to recognize the change.) +

Only administrators who belong to the cell's +system:administrators group can create user entries (the +group is itself defined in the Protection Database, as discussed in The System Groups). Members of the +system:administrators group can also create machine entries, +which can then be used to control access based on the machine from which the +access request originates. After creating a machine entry, add it to a +Protection Database group and place the group on ACLs (a machine cannot appear +on ACLs directly). A machine entry can represent a single machine or +multiple machines with consecutive IP addresses as specified by a wildcard +notation. For instructions, see Creating User and Machine Entries. Because all replicas of a volume share the same ACL +(the one on the volume's root directory mount point), machine entries +enable you to replicate the volume that houses a program's binary file +while still complying with a machine-based license agreement as required by +the program's manufacturer. See Creating User and Machine Entries. +

A group entry is a list of user entries, machine entries, or both (groups +cannot belong to other groups). Putting a group on an ACL is a +convenient way to extend or deny access to a set of users without listing them +on the ACL individually. Similarly, adding users to a group +automatically grants them access to all files and directories for which the +associated ACL lists that group. Both administrators and regular users +can create groups. + + + + + + +

The System Groups

In addition to the groups that users and administrators can +create, AFS defines the following three system groups. The Protection +Server creates them automatically when it builds the first version of a +cell's Protection Database, and always assigns them the same AFS +GIDs. +

system:anyuser +

Represents all users able to access the cell's filespace from the +local and foreign cells, authenticated or not. Its AFS GID is +-101. The group has no stable membership listed in the +Protection Database. Accordingly, the pts examine command +displays 0 in its membership field, and the pts +membership command does not list any members for it. +

Placing this group on an ACL is a convenient way to extend access to all +users. The File Server automatically places this group on the CPS of +any user who requests access to data stored on a file server machine. +(Every unauthenticated user is assigned the identity anonymous and +this group is the only entry on the CPS for anonymous.) +

system:authuser +

Represents all users who are able to access the cell's filespace from +the local and foreign cells and who have successfully obtained an AFS token in +the local cell (are authenticated). Its AFS GID is +-102. Like the system:anyuser group, it has +no stable membership listed in the Protection Database. Accordingly, +the pts examine command displays 0 in its +membership field, and the pts membership command does +not list any members for it. +

Placing this group on an ACL is therefore a convenient way to extend access +to all authenticated users. The File Server automatically places this +group on the CPS of any authenticated user who requests access to data stored +on a file server machine. +

system:administrators +

Represents the small number of cell administrators authorized to issue +privileged pts commands and the fs commands that set +quota. The ACL on the root directory of every newly created volume +grants all permissions to the group. Even if you remove that entry, the +group implicitly retains the a (administer), and by +default also the l (lookup), permission on every +ACL. Its AFS GID is -204. For instructions on +administering this group, see Administering the system:administrators Group. +

Displaying Information from the Protection Database

This section describes the commands you can use to display +Protection Database entries and associated information. In addition to +name and AFS ID, the Protection Database stores the following information +about each user, machine, or group entry. +

The entry's owner, which is the user or group of users who can +administer the entry +
The entry's creator, which serves mostly as an audit trail +
A membership count, which indicates how many groups a user or machine +belongs to, or how many members belong to a group +
A set of privacy flags, which control which users can administer or +display information about the entry +
A group-creation quota, which defines how many groups a user can create +
A list of the groups to which a user or machine belongs, or of the users +and machines that belong to a group +
A list of the groups that a user or group owns +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

To display a Protection Database entry

Verify that you belong to the system:administrators +group, which enables you to display an entry regardless of the setting of its +first (s) privacy flag. By default, any user can display a +Protection Database entry. If necessary, issue the pts +membership command, which is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts examine command to display one or more Protection +Database entries. +
```
   % pts examine <user or group name or id>⁺
+
```
+
where +
+
e +
Is the shortest acceptable abbreviation of examine (and +check is an alias). +
user or group name or id +
Specifies the name or AFS ID of each entry to display. Precede any +AFS GID with a hyphen (-) because it is a negative integer. +
+

The output includes the following fields. Examples follow. +

Name +

Specifies the entry's name. +

For a user, this is the name used when authenticating with AFS and the +name that appears on ACL entries. +
For a machine, this is the IP address of a single machine, or a wildcard +notation that represents a group of machines with consecutive IP addresses, as +described in Creating User and Machine Entries. +
For a group, this is the name that appears on ACL entries and in the list +of groups output by the pts membership command. The names of +regular groups have two parts, separated by a colon +(:). The part before the colon indicates the +group's owner, and the part after is the unique name. A +prefix-less group's name does not have the owner prefix; +only members of the system:administrators group can create +prefix-less groups. For further discussion of group names, see Creating Groups. +

+ + + +

id +

Specifies the entry's unique AFS identification number. For +user and machine entries, the AFS user ID (AFS UID) is a positive +integer; for groups, the AFS group ID (AFS GID) is a negative +integer. AFS UIDs and GIDs have the same function as their counterparts +in the UNIX file system, but are used by the AFS servers and the Cache Manager +only. +

Normally, the Protection Server assigns an AFS UID or GID automatically +when you create Protection Database entries. Members of the +system:administrators group can specify an ID if +desired. For further discussion, see Creating User and Machine Entries and Creating Groups. +

owner +

Names the user or group who owns the entry and therefore can administer it +(for more information about a group owning another group, see Using Groups Effectively). Other users possibly have administrative +privileges, too, depending on the setting of the entry's privacy +flags. For instructions on changing the owner, see Changing a Group's Owner. +

creator +

Names the user who created the entry, and serves as an audit trail. +If the entry is deleted from the Protection Database, the creator's group +creation quota increases by one, even if the creator no longer owns the +entry; see Setting Group-Creation Quota. +

The value anonymous in this field generally indicates that the +entry was created when the Protection Server was running in no-authentication +mode, probably during initial configuration of the cell's first file +server machine. For a description of no-authentication mode, see Managing Authentication and Authorization Requirements. +

membership +

Specifies the number of groups to which the user or machine belongs, or +the number of users or machines that belong to the group. +

flags +

Specifies who can display or change information in a Protection Database +entry. The five flags, each representing a different capability, always +appear in the same order. +

For user entries, the default value is S----, which indicates +that anyone can issue the pts examine command on the entry, but +only the user and members of the system:administrators group +can perform any other action. +
For machine entries, the default value is S----, which +indicates that anyone can issue the pts examine command on the +entry, but only members of the system:administrators group +can perform any other action. +
For group entries, the default value is S-M--, which indicates +that anyone can issue the pts examine and pts membership +commands on the entry, but only the group's owner and members of the +system:administrators group can perform any other +action. +

For a complete description of possible values for the flags, see Setting the Privacy Flags on Database Entries. +

group quota +

Specifies how many more groups a user can create in the Protection +Database. The value for a newly created user entry is 20, but members +of the system:administrators group can issue the pts +setfields command at any time to change the value; see Setting Group-Creation Quota. +

Group creation quota has no meaning for a machine or group entry: the +Protection Server recognizes the issuer of the pts creategroup +command only as an authenticated user or as the anonymous user, +never as a machine or group. The default value for group entries is 0 +(zero), and there is no reason to change it. +

The following examples show the output for a user called pat, a +machine with IP address 192.12.108.133 and a +group called terry:friends: +

   % pts examine pat
+   Name: pat, id: 1020, owner: system:administrators, creator: admin,
+     membership: 12, flags: S----, group quota: 15.
+   % pts ex 192.12.108.133
+   Name: 192.12.108.133, id: 5151, owner: system:administrators, creator: admin,
+     membership: 1, flags: S----, group quota: 20.
+   % pts examine terry:friends
+   Name: terry:friends, id: -567, owner: terry, creator: terry,
+     membership: 12, flags: SOm--, group quota: 0.
+

+ + + + + + + + + +

To display group membership

Verify that you belong to the system:administrators +group, which enables you to display an entry's group membership +information regardless of the setting of its third (m) privacy +flag. By default the owner and the user can display group membership +for a user entry, the owner for a machine entry, and anyone for a group +entry. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts membership command to display the list +of groups to which a user or machine belongs, or the list of users and +machines that belong to a group. +
```
   % pts membership <user or group name or id>⁺
+
```
+
where +
+
m +
Is the shortest acceptable abbreviation of membership. +
user or group name or id +
Specifies the name or AFS UID of each user or machine for which to list +the groups it belongs to, or the name or AFS GID of each group for which to +list the members. +
+

For user and machine entries, the output begins with the following string, +and then each group appears on its own line: +

   Groups user_or_machine (id: AFS_UID) is a member of:
+

For group entries, the output begins with the following string, and then +each member appears on its own line: +

   Members of group (id: AFS_GID) are:
+

For the system groups system:anyuser and +system:authuser, the output includes the initial header +string only, because these groups do not have a stable membership listed in +their Protection Database entry. See The System Groups. +

The following examples show the output for a user called terry +and a group called terry:friends: +

   % pts mem terry
+   Groups terry (id: 5347) is a member of:
+     pat:friends
+     sales
+     acctg:general
+   % pts mem terry:friends
+   Members of terry:friends (id: -567) are:
+     pat
+     smith
+     johnson
+

+ + + + + + + + +

To list the groups that a user or group owns

Verify that you belong to the system:administrators +group, which enables you to display an entry's group ownership +information regardless of the setting of its second (o) privacy +flag. By default the owner can list the groups owned by group, and a +user the groups he or she owns. If necessary, issue the pts +membership command, which is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts listowned command to list the groups owned by +each user or group. +
```
   % pts listowned <user or group name or id>⁺
+
```
+
where +
+
listo +
Is the shortest acceptable abbreviation of listowned. +
user or group name or id +
Specifies the name or AFS UID of each user, or the name or AFS GID or each +group, for which to list the groups owned. +
+

The output begins with the following string, and then each group appears on +its own line: +

   Groups owned by user_or_group (id: AFS_ID) are:
+

The following examples show the output for a user called terry +and a group called terry:friends: +

   % pts listo terry 
+   Groups owned by terry (id: 5347) are:  
+     terry:friends   
+     terry:co-workers
+   % pts listo terry:friends
+   Groups owned by terry:friends (id: -567) are:
+     terry:pals
+     terry:buddies
+

+ + + + + + + + + + + + + + + + + + +

To display all Protection Database entries

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts listentries command to display all Protection +Database entries. +
```
   % pts listentries [-users] [-groups]
+
```
+
where +
+
liste +
Is the shortest acceptable abbreviation of listentries. +
-users +
Displays user and machine entries. The same output results if you +omit both this flag and the -groups flag. +
-groups +
Displays group entries. +
+

The output is a table that includes the following columns. Examples +follow. +

Name +: Specifies the entry's name. +
ID +: Specifies the entry's AFS identification number. For user and +machine entries, the AFS user ID (AFS UID) is a positive integer; for +groups, the AFS group ID (AFS GID) is a negative integer. +
Owner +: Specifies the AFS ID of the user or group who owns the entry and therefore +can administer it. +
Creator +: Specifies the AFS UID of the user who created the entry. +

The following example is from the ABC Corporation cell. The issuer +provides no options, so the output includes user and machine entries. +

   % pts listentries
+   Name                          ID  Owner Creator
+   anonymous                  32766   -204    -204 
+   admin                          1   -204   32766 
+   pat                         1000   -204       1 
+   terry                       1001   -204       1 
+   smith                       1003   -204       1 
+   jones                       1004   -204       1 
+   192.12.105.33               2000   -204       1 
+   192.12.105.46               2001   -204       1 
+

+ + + + + +

Creating User and Machine Entries

An entry in the Protection Database is one of the two +required components of every AFS user account, along with an entry in the +Authentication Database. It is best to create a Protection Database +user entry only in the context of creating a complete user account, by using +the uss add or uss bulk command as described in Creating and Deleting User Accounts with the uss Command Suite, or the pts createuser command as described in Creating AFS User Accounts. +

You can also use the pts createuser command to create Protection +Database machine entries, which can then be used to control access based on +the machine from which the access request originates. After creating a +machine entry, add it to a Protection Database group and place the group on +ACLs ( a machine cannot appear on ACLs directly). Because all replicas +of a volume share the same ACL (the one on the volume's root directory +mount point), you can replicate the volume that houses a program's binary +file while still complying with a machine-based license agreement as required +by the program's manufacturer. If you do not place any other +entries on the ACL, then only users working on the designated machines can +access the file. +

Keep in mind that creating an ACL entry for a group with machine entries in +it extends access to both authenticated and unauthenticated users working on +the machine. However, you can deny access to unauthenticated users by +omitting an entry for the system:anyuser group from the ACLs +of the parent directories in the file's pathname. Conversely, if +you want to enable unauthenticated users on the machine to access a file, then +the ACL on every directory leading to it must include an entry for either the +system:anyuser group or a group to which the machine entry +belongs. For more information on the system:anyuser +group, see The System Groups. +

Because a machine entry can include unauthenticated users, it is best not +to add both machine entries and user entries to the same group. In +general, it is easier to use and administer nonmixed groups. A machine +entry can represent a single machine, or multiple machines with consecutive IP +addresses (that is, all machines on a network or subnet) specified by a +wildcard notation. See the instructions in To create machine entries in the Protection Database. +

By default, the Protection Server assigns the next available AFS UID to a +new user or machine entry. It is best to allow this, especially for +machine entries. For user entries, it makes sense to assign an AFS UID +only if the user already has a UNIX UID that the AFS UID needs to match (see Assigning AFS and UNIX UIDs that Match). When automatically allocating an AFS UID, the +Protection Server increments the max user id counter by one and +assigns the result to the new entry. Use the pts listmax +command to display the counter, as described in Displaying and Setting the AFS UID and GID Counters. + +

Do not reuse the AFS UIDs of users who have left your cell permanently or +machine entries you have removed, even though doing so seems to avoid the +apparent waste of IDs. When you remove a user or machine entry from the +Protection Database, the fs listacl command displays the AFS UID +associated with the former entry, rather than the name. If you then +assign the AFS UID to a new user or machine, the new user or machine +automatically inherits permissions that were granted to the previous possessor +of the ID. To remove obsolete AFS UIDs from ACLs, use the fs +cleanacl command described in Removing Obsolete AFS IDs from ACLs. +

In addition to the name and AFS UID, the Protection Server records the +following values in the indicated fields of a new user or machine's +entry. For more information and instructions on displaying an entry, +see To display a Protection Database entry. +

It sets the owner field to the +system:administrators group, indicating that the group's +members administer the entry. +
It sets the creator field to the username of the user who +issued the pts createuser command (or the uss add or +uss bulk command). +
It sets the membership field to 0 (zero), because +the new entry does not yet belong to any groups. +
It sets the flags field to S----; for +explanation, see Setting the Privacy Flags on Database Entries. +
It sets the group quota field to 20, meaning that +the new user can create 20 groups. This field has no meaning for +machine entries. For further discussion, see Setting Group-Creation Quota. +

+ + +

To create machine entries in the Protection Database

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts createuser command to create one or more machine +entries. +
```
   % pts createuser -name <user name>⁺ 
+
```
+
where +
+
cu +
Is an alias for createuser (and createu is the +shortest acceptable abbreviation). +
-name +
Specifies an IP address in dotted-decimal notation for each machine +entry. An entry can represent a single machine or a set of several +machines with consecutive IP addresses, using the wildcard notation described +in the following list. The letters W, X, +Y, and Z each represent an actual number value in the +field: +
- W.X.Y.Z represents a single machine, for +example 192.12.108.240. +
- W.X.Y.0 matches all machines whose IP +addresses start with the first three numbers. For example, +192.12.108.0 matches both +192.12.108.119 and +192.12.108.120, but does not match +192.12.105.144. +
- W.X.0.0 matches all machines whose IP +addresses start with the first two numbers. For example, the address +192.12.0.0 matches both +192.12.106.23 and +192.12.108.120, but does not match +192.5.30.95. +
- W.0.0.0 matches all machines whose IP +addresses start with the first number in the specified address. For +example, the address 192.0.0.0 matches both +192.5.30.95 and +192.12.108.120, but does not match +138.255.63.52. +
+
Do not define a machine entry with the name +0.0.0.0 to match every machine. The +system:anyuser group is equivalent. +
+

The following example creates a machine entry that includes all of the +machines in the 192.12 network. +

   % pts cu 192.12.0.0
+

+ + + + + + + + + +

Creating Groups

Before you can add members to a group, you must create the +group entry itself. The instructions in this section explain how to +create both regular and prefix-less groups: +

A regular group's name is preceded by a prefix that +indicates who owns the group, in the following format: +
owner_name:group_name +
Any user can create a regular group. Group names must always be +typed in full, so a short group_name that indicates the group's +purpose or its members' common interest is practical. Groups with +names like terry:1 and terry:2 are less +useful because their purpose is unclear. For more details on the +required format for regular group names, see the instructions in To create groups. +
A prefix-less group, as its name suggests, has only one field +in its name, equivalent to a regular group's group_name +field. +
Only members of the system:administrators group can create +prefix-less groups. For a discussion of their purpose, see Using Prefix-Less Groups. +

By default, the Protection Server assigns the next available AFS GID to a +new group entry, and it is best to allow this. When automatically +allocating an AFS GID (which is a negative integer), the Protection Server +decrements the max group id counter by one and assigns the result +to the new group. Use the pts listmax command to display the +counter, as described in Displaying and Setting the AFS UID and GID Counters. +

In addition to the name and AFS GID, the Protection Server records the +following values in the indicated fields of a new group's entry. +See To display a Protection Database entry. +

It sets the owner field to the issuer of the pts +creategroup command, or to the user or group specified by the +-owner argument. +
It sets the creator field to the username of the user who +issued the pts creategroup command. +
It sets the membership field to 0 (zero), because +the group currently has no members. +
It sets the flags field to S-M--; for +explanation, see Setting the Privacy Flags on Database Entries. +
It sets the group quota field to 0, because this +field has no meaning for group entries. +

+ + + + + + + + +

Using Groups Effectively

The main reason to create groups is to place them on ACLs, +which enables you to control access for multiple users without having to list +them individually on the ACL. There are three basic ways to use groups, +each suited to a different purpose: +

Private use: you create a group and place it on the ACL +of directories you own, without necessarily informing the group's members +that they belong to it. Members notice only that they can or cannot +access the directory in a certain way. You retain sole administrative +control over the group, since you are the owner. +
The existence of the group and the identity of its members is not +necessarily secret. Other users can use the fs listacl +command and see the group's name on a directory's ACL, or use the +pts membership command to list the groups they themselves belong +to. You can set the group's third privacy flag to limit who can +use the pts membership command to list the group's membership, +but a member of the system:administrators group always +can; see Setting the Privacy Flags on Database Entries. +

Shared use: you inform the group's members that they +belong to the group, but you still remain the sole administrator. For +example, the manager of a work group can create a group of all the members in +the work group, and encourage them to use it on the ACLs of directories that +house information they want to share with other members of the group. +

Note:

If you place a group owned by someone else on your ACLs, the group's +owner can change the group's membership without informing you. +Someone new can gain or lose access in a way you did not intend and without +your knowledge. +

Group use: you create a group and then use the pts +chown command to assign ownership to a group, either another group or +the group itself (the latter type is a self-owned group). +You inform the members of the owning group that they all can administer the +owned group. +
The main advantage of designating a group as an owner is that it spreads +responsibility for administering a group among several people. A single +person does not have to perform all administrative tasks, and if the original +creator leaves the group, ownership does not have to be transferred. +
However, everyone in the owner group can make changes that affect others +negatively, such as adding or removing people from the group inappropriately +or changing the group's ownership to themselves exclusively. These +problems can be particularly sensitive in a self-owned group. Using an +owner group works best if all the members know and trust each other; it +is probably wise to keep the number of people in an owner group small. +

+ + +

To create groups

If creating a prefix-less group, verify that you belong to the +system:administrators group. If necessary, issue the +pts membership command, which is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts creategroup command to create each group. +All of the groups have the same owner. +
```
   % pts creategroup  -name <group name>⁺ [-owner <owner of the group>]
+
```
+
where +
+
cg +
Is an alias for creategroup (and createg is the +shortest acceptable abbreviation). + + + +
-name +
Names each group to create. The name can include up to 63 lowercase +letters or numbers, but it is best not to include punctuation characters, +especially those that have a special meaning to the shell. +
A prefix-less group name cannot include the colon (:), +because it is used to separate the two parts of a regular group name: +
owner_name:group_name +
The Protection Server requires that the owner_name prefix of a +regular group name accurately indicate the group's owner. By +default, you are recorded as the owner, and the owner_name must be +your AFS username. You can include the -owner argument to +designate another AFS user, a regular group, or a prefix-less group as the +owner, providing the required value in the owner_name field: +
- If the owner is a user, it must be the AFS username. +
- If the owner is another regular group, it must match the owning +group's owner_name field. For example, if the owner is +the group terry:associates, the owner field must be +terry. +
- If the owner is a prefix-less group, it must be the owning group's +name. +
+
(For a discussion of why it is useful for a group to own another group, see +Using Groups Effectively.) +
-owner +
Is optional and designates an owner other than the issuer of the +command. Specify either an AFS username or the name of a regular or +prefix-less group that already has at least one member. Do not include +this argument if you want to make the group self-owned as described in Using Groups Effectively. For instructions, see To create a self-owned group. +
Do not designate a machine as a group's owner. Because a +machine cannot authenticate, there is no way for a machine to administer the +group. +
+

+ + + +

To create a self-owned group

Issue the pts creategroup command to create a group. Do +not include the -owner argument, because you must own a group to +reassign ownership. For complete instructions, see To create groups. +
```
   % pts creategroup  <group name>
+
```
+
Issue the pts adduser command to add one or more members to the +group (a group must already have at least one member before owning another +group). For complete instructions, see Adding and Removing Group Members. +
```
   % pts adduser -user <user name>⁺ -group <group name>⁺
+
```
+
Issue the pts chown command to assign group ownership to the +group itself. For complete instructions, see To change a group's owner. +
```
   % pts chown <group name> <new owner>
+
```
+

Using Prefix-Less Groups

Members of the system:administrators group +can create prefix-less groups, which are particularly suitable for group +use, which is described in Using Groups Effectively. +

Suppose, for example, that the manager of the ABC Corporation's +Accounting Department, user smith, creates a group that includes +all of the corporation's accountants and places the group on the ACLs of +directories that house departmental records. Using a prefix-less group +rather than a regular group is appropriate for the following reasons: +

The fact that smith created and owns the group is irrelevant, +and a regular group must be called smith:acctg. A +prefix-less name like acctg is more appropriate. +
If another user (say jones) ever replaces smith as +manager of the Accounting Department, jones needs to become the new +owner of the group. If the group is a regular one, its +owner_name prefix automatically changes to jones, but the +change in the owner_name prefix does not propagate to any regular +groups owned by the group. Someone must use the pts rename +command to change each one's owner_name prefix from +smith to jones. +

A possible solution is to create an authentication account for a fictional +user called acctg and make it the owner of regular groups which +have acctg as their owner_name prefix. However, if +the acctg account is also used for other purposes, then the number +of people who need to know user acctg's password is possibly +larger than the number of people who need to administer the groups it +owns. +

A prefix-less group called acctg solves the problem of +inappropriate owner names. The groups that it owns have +acctg as their owner_name prefix, which more accurately +reflects their purpose than having the manager's name there. +Prefix-less groups are also more accountable than dummy authentication +accounts. Belonging to the group enables individuals to exercise the +permissions granted to the group on ACLs, but users continue to perform tasks +under their own names rather than under the dummy username. Even if the +group owns itself, only a finite number of people can administer the group +entry. +

Adding and Removing Group Members

Users and machines can be members of groups; groups +cannot belong to other groups. Newly created groups have no members at +all. To add them, use the pts adduser command; to +remove them, use the pts removeuser command. + + + + + + + +

To add users and machines to groups

Verify that you belong to the system:administrators +group, which enables you to add members to a group regardless of the setting +of its fourth (a) privacy flag. By default the group's +owner also has the necessary privilege. If necessary, issue the +pts membership command, which is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts adduser command to add one or more members to one +or more groups. +
```
   % pts adduser -user <user name>⁺ -group <group name>⁺
+
```
+
where +
+
ad +
Is the shortest acceptable abbreviation of adduser. +
-user +
Specifies each username or machine IP address to add as a member of each +group named by the -group argument. A group cannot belong to +another group. +
group name +
Names each group to which to add the new members. +
+

+ + + + + + + +

To remove users and machines from groups

Verify that you belong to the system:administrators +group, which enables you to remove members from a group regardless of the +setting of its fifth (r) privacy flag. By default the +group's owner also has the necessary privilege. If necessary, +issue the pts membership command, which is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts removeuser command to remove one or more members +from one or more groups. +
```
   % pts removeuser -user  <user name>⁺  -group <group name>⁺
+
```
+
where +
+
rem +
Is the shortest acceptable abbreviation of removeuser. +
-user +
Specifies each user or machine IP address to remove from each group named +by the -group argument. +
-group +
Names each group from which to remove members. +
+

Deleting Protection Database Entries

It is best to delete a Protection Database user entry only +if you are removing the complete user account. Use either the uss +delete command as described in Deleting Individual Accounts with the uss delete Command, or the pts delete command as described in Removing a User Account. +

To remove machine and group entries, use the pts delete command +as described in this section. The operation has the following +results: +

When you delete a machine entry, its name (IP address wildcard) is removed +from groups. +
When you delete a group entry, its AFS GID appears on ACLs instead of the +name. The group-creation quota of the user who created the group +increases by one, even if the user no longer owns the group. +
To remove obsolete AFS IDs from ACLs, use the fs cleanacl +command as described in Removing Obsolete AFS IDs from ACLs. +

+ + + + + + + +

To delete Protection Database entries

Verify that you belong to the system:administrators group +or own the group you are deleting. If necessary, issue the pts +membership command, which is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts delete command to delete one or more entries from +the Protection Database. +
```
   % pts delete <user or group name or id>⁺
+
```
+
where +
+
del +
Is the shortest acceptable abbreviation of delete. +
user or group name or id +
Specifies the IP address or AFS UID of each machine or the name or AFS GID +or each group to remove. +
+

+ + +

Changing a Group's Owner

For user and machine entries, the Protection Server +automatically assigns ownership to the system:administrators +group at creation time, and this cannot be changed. For group entries, +you can change ownership. This transfers administrative responsibility +for it to another user or group (for information on group ownership of other +groups, see Using Groups Effectively). +

When you create a regular group, its owner_name prefix must +accurately reflect its owner, as described in To create groups: +

If the owner is a user, owner_name is the username. +
If the owner is a regular group, owner_name is the owning +group's owner_name prefix. +
If the owner is a prefix-less group, owner_name is the owner +group's name. +

When you change a regular group's owner, the Protection Server +automatically changes its owner_name prefix appropriately. For +example, if the user pat becomes the new owner of the group +terry:friends, its name automatically changes to +pat:friends, both in the Protection Database and on +ACLs. +

However, the Protection Server does not automatically change the +owner_name prefix of any regular groups that the group owns. +To continue with the previous example, suppose that the group +terry:friends owns the group +terry:pals. When pat becomes the new owner +of terry:friends, the name terry:pals does +not change. To change the owner_name prefix of a regular group +that is owned by another group (in the example, to change the group's +name to pat:pals), use the pts rename command as +described in Changing a Protection Database Entry's Name. + + + +

To change a group's owner

Verify that you belong to the system:administrators group +or own the group for which you are changing the owner. If necessary, +issue the pts membership command, which is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
(Optional) If you are changing the group's owner to +another group (or to itself) and want to retain administrative privilege on +the owned group, verify that you belong to the new owner group. If +necessary, issue the pts membership command, which is fully +described in To display group membership. +
```
   % pts membership <user or group name or id>
+
```
+
Use the pts adduser command to add yourself if necessary, as +fully described in To add users and machines to groups. +
```
   % pts adduser <user name> <group name>
+
```
+
Issue the pts chown command to change the group's +owner. +
```
   % pts chown <group name> <new owner>
+
```
+
where +
+
cho +
Is the shortest acceptable abbreviation of chown. +
group name +
Specifies the current name of the group. +
new owner +
Names the user or group to become the group's owner. +
+
(Optional) Issue the pts listowned command to +display any groups that the group owns. As discussed in the +introduction to this section, the pts chown command does not +automatically change the owner_name prefix of any regular groups that +a group owns. +
```
   % pts listowned <user or group name or id>
+
```
+
If you want to change their names to match the new owning group, use the +pts rename command on each one, as described in To change the name of a machine or group entry. +
```
   % pts rename <old name> <new name>
+
```
+

+ + + + + +

Changing a Protection Database Entry's Name

To change the name of a Protection Database entry, use the +pts rename command. It is best to change a user entry's +name only when renaming the entire user account, since so many components of +the account (Authentication Database entry, volume name, home directory mount +point, and so on) share the name. For instructions, see Changing Usernames. A machine entry's name maps to the actual IP +address of one or more machine, so changing the entry's name is +appropriate only if the IP addresses have changed. +

It is likely, then, that most often you need to change group names. +The following types of name changes are possible: +

Changing a regular group's name to another regular group name. +The most common reason for this type of change is that you have used the +pts chown command to change the owner of the group. That +operation does not change the owner_name prefix of a regular group +owned by the group whose name has been changed. Therefore, you must use +the pts rename command to change it appropriately. For +example, when user pat becomes the owner of the +terry:friends group, its name changes automatically to +pat:friends, but the name of a group it owns, +terry:pals, does not change. Use the pts +rename command to rename terry:pals to +pat:pals. The Protection Server does not accept +changes to the owner_name prefix that do not reflect the true +ownership (changing terry:pals to smith:pals +is not possible). +
You can also use the pts rename command to change the +group_name portion of a regular group name, with or without changing +the owner_name prefix. +
Both the group's owner and the members of the +system:administrators group can change its name to another +regular group name. +
Changing a regular group's name to a prefix-less name. If you +change a group's name in this way, you must also use the pts +rename command to change the name of any regular group that the group +owns. Only members of the system:administrators group +can make this type of name change. +
Changing a prefix-less name to another prefix-less name. As with +other name changes, the owner_name prefix of any regular groups that +the prefix-less group owns does not change automatically. You must +issue the pts rename command on them to maintain +consistency. +
Both the group's owner and the members of the +system:administrators group can change its name to another +prefix-less name. +
Changing a prefix-less name to a regular name. The +owner_name prefix on the new name must accurately reflect the +group's ownership. As with other name changes, the +owner_name prefix of any regular groups that the prefix-less group +owns does not change automatically. You must issue the pts +rename command on them to maintain consistency. +
Only members of the system:administrators group can make +this type of name change. +

+ + +

To change the name of a machine or group entry

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts rename command to change the entry's +name. +
```
   % pts rename <old name> <new name>
+
```
+
where +
+
ren +
Is the shortest acceptable abbreviation of rename. +
old name +
Specifies the entry's current name. +
new name +
Specifies the new name. If the new name is for a regular group, the +owner_name prefix must correctly indicate the owner. +
+

+ + + + + + +

Setting Group-Creation Quota

To prevent abuse of system resources, the Protection Server +imposes a group-creation quota that limits how many more groups a +user can create. When a new user entry is created, the quota is set to +20, but members of the system:administrators group can use +the pts setfields command to increase or decrease it at any +time. +

It is pointless to change group-creation quota for machine or group +entries. It is not possible to authenticate as a group or machine and +then create groups. +

To display the group-creation quota, use the pts examine command +to display a user entry's group quota field, as described in To display a Protection Database entry. + + +

To set group-creation quota

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts setfields command to specify how many more groups +each of one or more users can create. +
```
  % pts setfields -nameorid <user or group name or id>⁺  \
+                  -groupquota <set limit on group creation>
+
```
+
where +
+
setf +
Is the shortest acceptable abbreviation of setfields. +
-nameorid +
Specifies the name or AFS UID of each user for which to set group-creation +quota. +
-groupquota +
Defines how many groups each user can create in addition to existing +groups (in other words, groups that already exist do not count against the +quota). The value you specify overwrites the current value, rather than +incrementing it. +
+

+ + + + + + +

Setting the Privacy Flags on Database Entries

Members of the system:administrators group +can always display and administer Protection Database entries in any way, and +regular users can display and administer their own entries and any group +entries they own. The privacy flags on a Protection Database +entry determine who else can display certain information from the entry, and +who can add and remove members in a group. +

To display the flags, use the pts examine command as described +in To display a Protection Database entry. The flags appear in the output's +flags field. To set the flags, include the +-access argument to the pts setfields command. +

The five flags always appear, and always must be set, in the following +order: +

s +: Controls who can issue the pts examine command to display the +entry. +
o +: Controls who can issue the pts listowned command to display the +groups that a user or group owns. +
m +: Controls who can issue the pts membership command to display +the groups a user or machine belongs to, or which users or machines belong to +a group. +
a +: Controls who can issue the pts adduser command to add a user or +machine to a group. It is meaningful only for groups, but a value must +always be set for it even on user and machine entries. +
r +: Controls who can issue the pts removeuser command to remove a +user or machine from a group. It is meaningful only for groups, but a +value must always be set for it even on user and machine entries. +

Each flag can take three possible types of values to enable a different set +of users to issue the corresponding command: +

A hyphen (-) designates the members of the +system:administrators group and the entry's +owner. For user entries, it designates the user in addition. +
The lowercase version of the letter applies meaningfully to groups only, +and designates members of the group in addition to the individuals designated +by the hyphen. +
The uppercase version of the letter designates everyone. +

For example, the flags SOmar on a group entry indicate that +anyone can examine the group's entry and display the groups that it owns, +and that only the group's members can display, add, or remove its +members. +

The default privacy flags for user and machine entries are +S----, meaning that anyone can display the entry. The +ability to perform any other functions is restricted to members of the +system:administrators group and the entry's owner (as +well as the user for a user entry). +

The default privacy flags for group entries are S-M--, meaning +that all users can display the entry and the members of the group, but only +the entry owner and members of the system:administrators +group can perform other functions. + + +

To set a Protection Database entry's privacy flags

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts setfields command to set the privacy +flags. +
```
   % pts setfields <user or group name or id>⁺ -access <set privacy flags>
+
```
+
where +
+
setf +
Is the shortest acceptable abbreviation of setfields. +
user or group name or id +
Specifies the name or AFS UID of each user, the IP address or AFS UID of +each machine, or the name or AFS GID of each group for which to set the +privacy flags. +
-access +
Specifies the set of privacy flags to associate with each entry. +Provide a value for each of the five flags, observing the following +constraints: +
- Provide a value for all five flags, even though the fourth and fifth flags +are not meaningful for user and machine entries. +
- For self-owned groups, the hyphen is equivalent to a lowercase letter, +because all the members of a self-owned group own it. +
- Set the first flag to lowercase s or uppercase S +only. For user and machine entries, the Protection Server interprets +the lowercase s as equivalent to the hyphen. +
- Set the second flag to the hyphen (-) or uppercase O +only. For groups, the Protection Server interprets the hyphen as +equivalent to lowercase o (that is, members of a group can always +list the groups that it owns). +
- Set the third flag to the hyphen (-), lowercase m, +or uppercase M. For user and machine entries, the lowercase +m does not have a meaningful interpretation, because they have no +members. +
- Set the fourth flag to the hyphen (-), lowercase a, +or uppercase A. Although this flag does not have a +meaningful interpretation for user and machine entries (because they have no +members), it must be set, preferably to the hyphen. +
- Set the fifth flag to the hyphen (-) or lowercase r +only. Although this flag does not have a meaningful interpretation for +user and machine entries (because they have no members), it must be set, +preferably to the hyphen. +
+
+

+ + + + +

Displaying and Setting the AFS UID and GID Counters

When you use the pts createuser command to create +a user or machine entry in the Protection Database, the Protection Server by +default automatically allocates an AFS user ID (AFS UID) for it; +similarly, it allocates an AFS group ID (AFS GID) for each group entry you +create with the pts creategroup command. It tracks the next +available AFS UID (which is a positive integer) and AFS GID (which is a +negative integer) with the max user id and max group id +counters, respectively. +

Members of the system:administrators group can include the +-id argument to either pts creation command to assign a +specific ID to a new user, machine, or group. It often makes sense to +assign AFS UIDs explicitly when creating AFS accounts for users with existing +UNIX accounts, as discussed in Assigning AFS and UNIX UIDs that Match. It is also useful if you want to establish ranges of +IDs that correspond to departmental affiliations (for example, assigning AFS +UIDs from 300 to 399 to members of one department, AFS UIDs from 400 to 499 to +another department, and so on). +

To display the current value of the counters, use the pts +listmax command. When you next create a user or machine entry and +do not specify its AFS UID, the Protection Server increments the max user +id counter by one and assigns that number to the new entry. When +you create a new group and do not specify its AFS GID, the Protection Server +decrements the max group id counter by one (makes it more +negative), and assigns that number to the new group. +

You can change the value of either counter, or both, in one of two +ways: +

Directly, using the pts setmax command. +
Indirectly, by using the -id argument to the pts +createuser command to assign an AFS UID that is larger than the max +user id counter, or by using the -id to the pts +creategroup command to assign an AFS GID that is less (more negative) +than the max group id counter. In either case, the +Protection Server changes the counter to the value of the -id +argument. The Protection Server does not use the IDs between the +previous value of the counter and the new one when allocating IDs +automatically, unless you use the pts setmax command to move the +counter back to its old value. +
If the value you specify with the -id argument is less than the +max user id counter or greater (less negative) than the max +group id counter, then the counter does not change. +

+ + + + + + +

To display the AFS ID counters

Issue the pts listmax command to display the counters. +
```
   % pts listmax
+
```
+
where listm is an acceptable abbreviation of +listmax. +

The following example illustrates the output's format. In this +case, the next automatically assigned AFS UID is 5439 and AFS GID is +-469. +

   % pts listmax
+   Max user id is 5438 and max group id is -468.
+

+ + + + + + + + + + + +

To set the AFS ID counters

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts setmax command to set the max user id +counter, the max group id counter, or both. +
```
   % pts setmax [-group <group max>] [-user <user max>]
+
```
+
where +
+
setm +
Is the shortest acceptable abbreviation of setmax. +
-group +
Specifies an integer one greater (less negative) than the AFS GID that the +Protection Server is to assign to the next group entry. Because the +value is a negative integer, precede it with a hyphen (-). +
-user +
Specifies an integer one less than the AFS UID that the Protection Server +is to assign to the next user or machine entry. +
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd020.htm b/doc/html/AdminGuide/auagd020.htm new file mode 100644 index 0000000..211024d --- /dev/null +++ b/doc/html/AdminGuide/auagd020.htm @@ -0,0 +1,939 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Managing Access Control Lists

To control access to a directory and all of the files in it, +AFS associates an access control list (ACL) with it, +rather than the mode bits that the UNIX file system (UFS) associates with +individual files or directories. AFS ACLs provide more refined access +control because there are seven access permissions rather than UFS's +three, and there is room for approximately 20 user or group entries on an ACL, +rather than just the three UFS entries (owner, group, +and other). +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + +
Examine access control list + fs listacl +
Edit ACL's normal permissions section + fs setacl +
Edit ACL's negative permissions section + fs setacl with -negative flag +
Replace an ACL + fs setacl with -clear flag +
Copy an ACL + fs copyacl +
Remove obsolete AFS UIDs + fs cleanacl +
+

Protecting Data in AFS

+ + +

This section describes the main differences between the AFS and UFS file +protection systems, discusses the implications of directory-level protections, +and describes the seven access permissions. +

Differences Between UFS and AFS Data Protection

+ + + +

The UFS mode bits data protection system and the AFS ACL system differ in +the following ways: +

Protection at the file level (UFS) versus the directory level (AFS) +
UFS associates a set of nine mode bits with each file element, three +(rwx) for each of the element's owner, owning group, and all +other users. A similar set of mode bits on the file's directory +applies to the file only in an oblique way. +
An AFS ACL instead protects all files in a directory in the same +way. If a certain file is more sensitive than others, store it in a +directory with a more restrictive ACL. +
Defining access at the directory level has important consequences: + +
- The permissions on a directory's ACL apply to all of the files in the +directory. When you move a file to a different directory, you +effectively change the access permissions that apply to it to those on its new +directory's ACL. Changing a directory's ACL changes the +protection on all the files in it. +
- When you create a subdirectory, its initial ACL is created as a copy of +its parent directory's ACL. You can then change the +subdirectory's ACL independently. However, the parent +directory's ACL continues to control access to the subdirectory in the +following way: the parent directory's ACL must grant the +l (lookup) permission to a user (or a group the user +belongs to) in order for the user to access the subdirectory at all. +
  In general, then, it is best to assign fairly liberal access permissions to +high-level directories (including user home directories). In +particular, it often makes sense to grant at least the l permission +to the system:anyuser or system:authuser +group on high-level directories. For further discussion, see Using Groups on ACLs. +
+
How the mode bits are interpreted +
Mode bits are the only file-protection system in UFS. AFS allows you +to set the UNIX mode bits on a file in addition to the ACL on its directory, +but it interprets them differently. See How AFS Interprets the UNIX Mode Bits. +
Three access permissions (UFS) versus seven (AFS) +
UFS defines three access permissions in the form of mode bits: +r (read), w (write), and +x (execute). AFS defines seven permissions, which +makes access control more precise. For detailed descriptions, see The AFS ACL Permissions. +
+
a (administer) +
d (delete) +
i (insert) +
k (lock) +
l (lookup) +
r (read) +
w (write) +
+
Three defined users and groups (UFS) versus many (AFS) +
UFS controls access for one user and two groups by providing a set of mode +bits for each: the user who owns the file or directory, a single defined +group, and everyone who has an account on the system. +
AFS, in contrast, allows you to place many entries (individual users or +groups) on an ACL, granting a different set of access permissions to each +one. The number of possible entries is about 20, and depends on how +much space each entry occupies in the memory allocated for the ACL +itself. +
AFS defines two system groups, system:anyuser and +system:authuser, which represent all users and all +authenticated users, respectively; for further discussion, see Using Groups on ACLs. In addition, users can define their own groups in +the Protection Database, consisting of individual users or machine IP +addresses. Users who have the a permission on an ACL can +create entries for the system groups as well as groups defined by themselves +or other users. For information on defining groups, see Administering the Protection Database. +
When a user requests access to a file or directory, the File Server sums +together all of the permissions that the relevant ACL extends to the user and +to groups to which the user belongs. Placing group entries on ACLs +therefore can control access for many more users than the ACL can accommodate +as individual entries. +

The AFS ACL Permissions

+ + + +

Functionally, the seven standard ACL permissions fall into two +groups: one that applies to the directory itself and one that applies to +the files it contains. +

The Four Directory Permissions

The four permissions in this group are meaningful with +respect to the directory itself. For example, the i +(insert) permission does not control addition of data to a file, +but rather creation of a new file or subdirectory. +

The l (lookup) permission +

This permission functions as something of a gate keeper for access to the +directory and its files, because a user must have it in order to exercise any +other permissions. In particular, a user must have this permission to +access anything in the directory's subdirectories, even if the ACL on a +subdirectory grants extensive permissions. + + +

This permission enables a user to issue the following commands: +

The ls command to list the names of the files and +subdirectories in the directory +
The ls -ld command to obtain complete status information for +the directory element itself +
The fs listacl command to examine the directory's ACL +

This permission does not enable a user to read the contents of a file in +the directory, to issue the ls -l command on a file in the +directory, or to issue the fs listacl command with the filename as +the -path argument. Those operations require the +r (read) permission which is described in The Three File Permissions. +

Similarly, this permission does not enable a user to issue the +ls, ls -l, ls -ld, or fs listacl +commands against a subdirectory of the directory. Those operations +require the l permission on the ACL of the subdirectory +itself. +

The i (insert) permission +

This permission enables a user to add new files to the directory, either +by creating or copying, and to create new subdirectories. It does not +extend into any subdirectories, which are protected by their own ACLs. + + +

The d (delete) permission +

This permission enables a user to remove files and subdirectories from the +directory or move them into other directories (assuming that the user has the +i permission on the ACL of the other directories). + + +

The a (administer) permission +

This permission enables a user to change the directory's ACL. +Members of the system:administrators group implicitly have +this permission on every directory (that is, even if that group does not +appear on the ACL). Similarly, the owner of a directory implicitly has +this permission on its ACL and those of all directories below it that he or +she owns. + + +

The Three File Permissions

The three permissions in this group are meaningful with +respect to files in a directory, rather than the directory itself or its +subdirectories. +

The r (read) permission +: This permission enables a user to read the contents of files in the +directory and to issue the ls -l command to stat the file +elements. + + +
The w (write) permission +: This permission enables a user to modify the contents of files in the +directory and to issue the chmod command to change their UNIX mode +bits. + + +
The k (lock) permission +: This permission enables the user to run programs that issue system calls +to lock files in the directory. + + +

The Eight Auxiliary Permissions

+ + + +

AFS provides eight additional permissions that do not have a defined +meaning, denoted by the uppercase letters A, B, +C, D, E, F, G, and +H. +

You can write application programs that assign a meaning to one or more of +the permissions, and then place them on ACLs to control file access by those +programs. For example, you can modify a print program to recognize and +interpret the permissions, and then place them on directories that house files +that the program accesses. Use the fs listacl and fs +setacl commands to display and set the auxiliary permissions on ACLs +just like the standard seven. +

Shorthand Notation for Sets of Permissions

+ + +

You can combine the seven permissions in any way in an ACL entry, but +certain combinations are more useful than others. Four of the more +common combinations have corresponding shorthand forms. When using the +fs setacl command to define ACL entries, you can provide either one +or more of the individual letters that represent the permissions, or one of +the following shorthand forms: +

all +: Represents all seven standard permissions (rlidwka). + +
none +: Removes the entry from the ACL, leaving the user or group with no +permissions. + +
read +: Represents the r (read) and l +(lookup) permissions. + +
write +: Represents all permissions except a +(administer): rlidwk. +

Using Normal and Negative Permissions

+ + + +

ACLs enable you both to grant and to deny access to a directory and the +files in it. To grant access, use the fs setacl command to +create an ACL entry that associates a set of permissions with a user or group, +as described in Setting ACL Entries. When you use the fs listacl command to +display an ACL (as described in Displaying ACLs), such entries appear underneath the following header, which +uses the term rights to refer to permissions: +

   Normal rights
+

There are two ways to deny access: +

The recommended method is simply to omit an entry for the user or group +from the ACL, or to omit the appropriate permissions from the entry. +Use the fs setacl command to remove or edit an existing entry, +using the instructions in To add, remove, or edit normal ACL permissions. In most circumstances, this method is enough to +prevent access of certain kinds or by certain users. You must take +care, however, not to grant the undesired permissions to any groups to which +such users belong. +
The more explicit method for denying access is to use the +-negative flag to the fs setacl command to create an +entry that associates negative permissions with the user or +group; for instructions, see To add, remove, or edit negative ACL permissions. The output from the fs listacl +command lists negative entries underneath the following header: +
```
   Negative rights
+
```
+
When determining what type of access to grant to a user, the File Server +first compiles a set of permissions by examining all of the entries in the +Normal rights section of the ACL. It then subtracts any +permissions associated with the user (or with groups to which the user +belongs) on the Negative rights section of the ACL. +Therefore, negative permissions always cancel out normal permissions. +
Using negative permissions reverses the usual semantics of the fs +setacl command, introducing the potential for confusion. In +particular, combining the none shorthand and the +-negative flag constitutes a double negative: by removing an +entry from the Negative rights section of the ACL, you enable a +user once again to obtain permissions via entries in the Normal +rights section. Combining the all shorthand with the +-negative flag explicitly denies all permissions. +
Note also that it is pointless to create an entry in the Negative +rights section if an entry in the Normal rights section +grants the denied permissions to the system:anyuser +group. In this case, users can obtain the permissions simply by using +the unlog command to discard their tokens. When they do so, +the File Server recognizes them as the anonymous user, who belongs +to the system:anyuser group but does not match the entries on +the Negative rights section of the ACL. +

Using Groups on ACLs

+ + +

As previously mentioned, placing a group entry on an ACL enables you to +control access for many users at once. You can grant a new user access +to many files and directories simply by adding the user to a group that +appears on the relevant ACLs. You can also create groups of machines, +in which case any user logged on to the machine obtains the access that is +granted to the group. On directories where they have the a +permission on the ACL, users can define their own groups and can create ACL +entries for any groups, not just groups that they create or own +themselves. For instructions on creating groups of users or machines, +and a discussion of the most effective ways to use different types of groups, +see Administering the Protection Database. + + + + + +

AFS also defines the following two system groups, which can be very useful +on ACLs because they potentially represent a large group of people. For +more information about these groups, see The System Groups. +

system:anyuser +

Includes anyone who can access the cell's file tree, including users +who have logged in as the local superuser root, have connected to a +local machine from somewhere outside the cell, and AFS users who belong to a +foreign cell. This group includes users who do not have tokens that are +valid for the local AFS servers; the servers recognize them as the user +anonymous. +

Note that creating an ACL entry for this group is the only way to extend +access to AFS users from foreign cells, unless you create local authentication +accounts for them. + +

system:authuser +

Includes all users who have a valid AFS token obtained from the local +cell's authentication service. +

It is particularly useful to grant the l (lookup) +permission to the system:anyuser group on the ACL of most +directories in the file system, especially at the upper levels. This +permission enables users only to learn the names of files and subdirectories +in a directory, but without it they cannot traverse their way through the +directories in the path to a target file. +

A slightly more restrictive alternative is to grant the l +permission to the system:authuser group. If that is +still not restrictive enough, you can grant the l to specific users +or groups, which cannot exceed about 20 in number on a given ACL. +

Another reason to grant certain permissions to the +system:anyuser group is to enable the correct operation of +processes that provide services such as printing and mail delivery. For +example, in addition to the l permission, a print process possibly +needs the r (read) permission in order to access the +contents of files, and a mail delivery process possibly requires the +i (insert) permission to deliver new pieces of +mail. +

The ACL on the root directory of every newly created volume grants all +permissions to the system:administrators group. You +can remove this entry if you wish, but members of the +system:administrators group always implicitly have the +a (administer), and by default also the l, +permission on every directory's ACL. The a permission +enables them to grant themselves other permissions explicitly when +necessary. To learn about changing this default set of permissions, see +Administering the system:administrators Group. +

Displaying ACLs

+ + +

To display the ACL associated with a file, directory or symbolic link, +issue the fs listacl command. The output for a symbolic link +displays the ACL that applies to its target file or directory, rather than the +ACL on the directory that houses the symbolic link. +

Note for AFS/DFS Migration Toolkit users: If the machine +on which you issue the fs listacl command is configured to access a +DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can use +the command to display the ACL on DFS files and directories. To display +a DFS directory's Initial Container and Initial Object ACL instead of the +regular one, include the fs listacl command's -id +or -if flag. For instructions, see the IBM AFS/DFS +Migration Toolkit Administration Guide and Reference. The +fs command interpreter ignores the -id and +-if flags if you include them when displaying an AFS ACL. + + +

To display an ACL

Issue the fs listacl command. +
```
   % fs listacl [<dir/file path>⁺]
+
```
+
where +
+
la +
Is an acceptable alias for listacl (and lista is the +shortest acceptable abbreviation). +
dir/file path +
Names one or more files or directories for which to display the +ACL. For files, the output displays the ACL for its directory. +If you omit this argument, the output is for the current working +directory. Partial pathnames are interpreted relative to the current +working directory. You can also use the following notation on its own +or as part of a pathname: +
+
. +
(A single period). Specifies the current working directory. +
.. +
(Two periods). Specifies the current working directory's +parent directory. +
* +
(The asterisk). Specifies each file and subdirectory in the current +working directory. The ACL displayed for a file is always the same as +for its directory, but the ACL for each subdirectory can differ. +
+
+

The following error message indicates that you do not have the permissions +needed to display an ACL. To specify a directory name as the +dir/file path argument, you must have the l +(lookup) permission on the ACL. To specify a filename, you +must also have the r (read) permission on its +directory's ACL. +

   fs: You don't have the required access permissions on 'dir/file path'
+

Members of the system:administrators group and the +directory's owner (as reported by the ls -ld command) +implicitly have the a (administer) permission on every +directory's ACL, and can use the fs setacl command to grant +themselves the required permissions; for instructions, see Setting ACL Entries. +

The output for each file or directory specified as dir/file path +begins with the following header to identify it: +

   Access list for  dir/file path is
+

The Normal rights header appears on the next line, followed by +lines that each pair a user or group name and a set of permissions. The +permissions appear as the single letters defined in The AFS ACL Permissions, and always in the order rlidwka. If there +are any negative permissions, the Negative rights header appears +next, followed by pairs of negative permissions. +

The following example displays the ACL on user terry's home +directory in the ABC Corporation cell: +

   % fs la /afs/abc.com/usr/terry
+   Access list for /afs/abc.com/usr/terry is
+   Normal permissions:
+      system:authuser rl
+      pat rlw
+      terry rlidwka
+   Negative permissions:
+      terry:other-dept rl
+      jones rl
+

where pat, terry, and jones are individual +users, system:authuser is a system group, and +terry:other-dept is a group that terry +owns. The list of normal permissions grants all permissions to +terry, the r (read), l +(lookup), and w (write) permissions to +pat, and the r and l permissions to the +members of the system:authuser group. +

The list of negative permissions denies the r and l +permissions to jones and the members of the +terry:other-dept group. These entries effectively +prevent them from accessing terry's home directory in any way, +because they cancel out the r and l permissions extended +to the system:authuser group, which is the only entry on the +Normal rights section of the ACL that possibly applies to +them. +

Setting ACL Entries

+ + + + + + + + + + +

To add, remove, or edit ACL entries, use the fs setacl +command. By default, the command manipulates entries on the normal +permissions section of the ACL. To manipulate entries on the negative +permissions section, include the -negative flag. +

You must have the a (administer) permission on an ACL +to edit it. The owner of a directory (as reported by the ls +-ld) command and members of the system:administrators +group always implicitly have it on every ACL. By default, members of +the system:administrators group also implicitly have the +l (lookup) permission. +

Note for AFS/DFS Migration Toolkit users: If the machine +on which you issue the fs setacl command is configured to access a +DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can use +the command to set the ACL on DFS files and directories. To set a DFS +directory's Initial Container and Initial Object ACL instead of the +regular one, include the fs setacl command's -id or +-if flag. For instructions, see the IBM AFS/DFS +Migration Toolkit Administration Guide and Reference. The +fs command interpreter ignores the -id and +-if flags if you include them when setting an AFS ACL. + + +

To add, remove, or edit normal ACL permissions

Verify that you have the a (administer) permission +on each directory for which you are editing the ACL. If necessary, +issue the fs listacl command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Issue the fs setacl command to edit entries in the normal +permissions section of the ACL. To remove an entry, specify the +none shorthand as the permissions. If an ACL entry already +exists, the permissions you specify completely replace those in the existing +entry. +
```
   % fs setacl  -dir <directory>⁺ -acl <access list entries>⁺
+
```
+
where +
+
sa +
Is an acceptable alias for setacl (and seta is the +shortest acceptable abbreviation). +
-dir +
Names one or more directories to which to apply the ACL entries defined by +the -acl argument. Partial pathnames are interpreted +relative to the current working directory. +
Specify the read/write path to each directory, to avoid the failure that +results when you attempt to change a read-only volume. By convention, +you indicate the read/write path 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 Rules of Mount Point Traversal. +
You can also use the following notation on its own or as part of a +pathname: +
+
. +
(A single period). If used by itself, sets the ACL on the current +working directory. +
.. +
(Two periods). If used by itself, sets the ACL on the current +working directory's parent directory. +
* +
(The asterisk). Sets the ACL on each of the subdirectories in the +current working directory. You must precede it with the -dir +switch, since it potentially designates multiple directories. The +fs command interpreter generates the following error message for +each file in the directory: +
fs: 'filename': Not a directory +
+
+
If you specify only one directory or file name, you can omit the +-dir and -acl switches. +
-acl +
Specifies one or more ACL entries, each of which pairs a user or group +name and a set of permissions. Separate the pairs, and the two parts of +each pair, with one or more spaces. +
To define the permissions, provide either: +
- One or more of the letters that represent the standard or auxiliary +permissions (rlidwka and ABCDEFGH), in any order +
- One of the four shorthand notations: +
  - all (equals rlidwka) +
  - none (removes the entry) +
  - read (equals rl) +
  - write (equals rlidwk) +
  +
+
For a more detailed description of the permissions and shorthand notations, +see The AFS ACL Permissions. +
On a single command line, you can combine user and group entries. +You can also use individual letters in some pairs and the shorthand notations +in other pairs, but cannot combine letters and shorthand notation within a +single pair. +
+

Either of the following examples grants user pat the +r (read) and l (lookup) +permissions on the ACL of the notes subdirectory in the +issuer's home directory. They illustrate how it is possible to +omit the -dir and -acl switches when you name only one +directory. +

   % fs sa ~/notes pat rl
+   
+   % fs sa ~/notes pat read
+

The following example edits the ACL for the current working +directory. It removes the entry for the system:anyuser +group, and adds two entries: one grants all permissions except +a (administer) to the members of the +terry:colleagues group and the other grants the r +(read) and l (lookup) permissions to the +system:authuser group. The command appears on two +lines here only for legibility. +

   % fs  sa  -dir . -acl  system:anyuser  none  terry:colleagues  write  \
+           system:authuser  rl
+

+ + + + + +

To add, remove, or edit negative ACL permissions

Verify that you have the a (administer) permission +on each directory for which you are editing the ACL. If necessary, +issue the fs listacl command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Issue the fs setacl command with the -negative flag +to edit entries in the negative permissions section of the ACL. To +remove an entry, specify the none shorthand as the +permissions. If an ACL entry already exists for a user or group, the +permissions you specify completely replace those in the existing entry. +
```
   % fs setacl -dir <directory>⁺ -acl <access list entries>⁺  -negative 
+
```
+
where +
+
sa +
Is an acceptable alias for setacl (and seta is the +shortest acceptable abbreviation). +
-dir +
Names one or more directories to which to apply the negative ACL entries +defined by the -acl argument. Specify the read/write path to +each directory, to avoid the failure that results when you attempt to change a +read-only volume. For a detailed description of acceptable values, see To add, remove, or edit normal ACL permissions. +
-acl +
Specifies one or more ACL entries, each of which pairs a user or group +name and a set of permissions. Separate the pairs, and the two parts of +each pair, with one or more spaces. For a detailed description of +acceptable values, see To add, remove, or edit normal ACL permissions. Keep in mind that the usual meaning of each +permission is reversed. +
-negative +
Places the entries defined by the -acl argument on the negative +permissions section of the ACL for each directory named by the -dir +argument. +
+

The following example denies user pat the w +(write) and d (delete) permissions for the +project subdirectory of the current working directory. +

   % fs sa project pat wd -neg
+

Completely Replacing an ACL

+ + + + + + +

It is sometimes simplest to clear an ACL completely before defining new +permissions on it, for instance if the mix of normal and negative permissions +makes it difficult to understand how their interaction affects a user's +access to the directory. To clear an ACL completely while you define +new entries, include the -clear flag on the fs setacl +command. When you include this flag, you can create entries on either +the normal permissions or the negative permissions section of the ACL, but not +on both at once. +

Remember to create an entry that grants appropriate permissions to the +directory's owner. The owner implicitly has the a +(administer) permission required to replace a deleted entry, but +the effects of a missing ACL entry (particularly the lack of the +lookup permission) can be so confusing that it becomes difficult +for the owner to realize that the missing entry is causing the +problems. + + +

To replace an ACL completely

Verify that you have the a (administer) permission +on each directory for which you are editing the ACL. If necessary, +issue the fs listacl command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Issue the fs setacl command with the -clear flag to +clear the ACL completely before setting either normal or negative +permissions. Because you need to grant the owner of the directory all +permissions, it is better in most cases to set normal permissions at this +point. +
```
   % fs setacl -dir <directory>⁺ -acl <access list entries>⁺ -clear  \
+               [-negative] 
+
```
+
where +
+
sa +
Is an acceptable alias for setacl (and seta is the +shortest acceptable abbreviation). +
-dir +
Names one or more directories to which to apply the negative ACL entries +defined by the -acl argument. Specify the read/write path to +each directory, to avoid the failure that results when you attempt to change a +read-only volume. For a detailed description of acceptable values, see To add, remove, or edit normal ACL permissions. +
-acl +
Specifies one or more ACL entries, each of which pairs a user or group +name and a set of permissions. Separate the pairs, and the two parts of +each pair, with one or more spaces. Remember to grant all permissions +to the owner of the directory. For a detailed description of acceptable +values, see To add, remove, or edit normal ACL permissions. +
-clear +
Removes all entries from each ACL before creating the entries indicated by +the -acl argument. +
-negative +
Places the entries defined by the -acl argument on the negative +permissions section of each ACL. +
+

Copying ACLs Between Directories

+ + + +

The fs copyacl command copies a source directory's ACL to +one or more destination directories. It does not affect the source ACL +at all, but changes each destination ACL as follows: +

If an entry on the source ACL does not exist on the destination ACL, the +command copies it to the destination ACL. +
If an entry on the destination ACL does not also exist on the source ACL, +the command does not remove it unless you include the -clear flag +to overwrite the destination ACL completely. +
If an entry is on both ACLs, the command changes the permissions on the +destination ACL entry to match the source ACL entry. +

Note for AFS/DFS Migration Toolkit users: If the machine +is configured to enable AFS users to access a DCE cell's DFS filespace +via the AFS/DFS Migration Toolkit, then you can use the fs copyacl +command to copy ACLs between DFS files and directories also. The +command includes -id and -if flags for altering a DFS +directory's Initial Container and Initial Object ACLs as well as its +regular ACL; see the IBM AFS/DFS Migration Toolkit Administration +Guide and Reference. You cannot copy ACLs between AFS and DFS +directories, because they use different ACL formats. The fs +command interpreter ignores the -id and -if flags if you +include them when copying AFS ACLs. + + +

To copy an ACL between directories

Verify that you have the l (lookup) permission on +the source ACL and the a (administer) permission on each +destination ACL. To identify the source directory by naming a file in +it, you must also have the r (read) permission on the +source ACL. If necessary, issue the fs listacl command, +which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Issue the fs copyacl command to copy a source ACL to +the ACL on one or more destination directories. (The command appears +here on two lines only for legibility.) +
```
   % fs copyacl -fromdir <source directory> -todir <destination directory>⁺  \
+                [-clear]
+
```
+
where +
+
co +
Is the shortest acceptable abbreviation for copyacl. +
-fromdir +
Names the source directory from which to copy the ACL. Partial +pathnames are interpreted relative to the current working directory. If +this argument names a file, the ACL is copied from its directory. +
-todir +
Names each destination directory to which to copy the source ACL. +Partial pathnames are interpreted relative to the current working +directory. Filenames are not acceptable. +
Specify the read/write path to each directory, to avoid the failure that +results when you attempt to change a read-only volume. By convention, +you indicate the read/write path 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 Rules of Mount Point Traversal. +
-clear +
Completely overwrites each destination directory's ACL with the +source ACL. +
+

The following example copies the ACL from the current working +directory's notes subdirectory to the plans +subdirectory. The issuer does not include the -clear flag, +so the entry for user pat remains on the plans +directory's ACL although there is no corresponding entry on the +notes directory's ACL. +

   % fs la notes plans
+   Access list for notes is
+   Normal permissions:
+      terry rlidwka
+      smith rl
+      jones rl
+   Access list for plans is
+   Normal permissions:
+      terry rlidwk
+      pat rlidwk
+   % fs copyacl notes plans
+   % fs la notes plans
+   Access list for notes is
+   Normal permissions:
+      terry rlidwka
+      smith rl
+      jones rl
+   Access list for plans is
+   Normal permissions:
+      terry rlidwka
+      pat rlidwk
+      smith rl
+      jones rl
+

+ + + + + +

Removing Obsolete AFS IDs from ACLs

When you remove a user or group entry from the Protection +Database, the fs listacl command displays the user's AFS UID +(or group's AFS GID) in ACL entries, rather than the name. In the +following example, user terry has an ACL entry for the group +terry:friends (AFS GID -567) on her home directory in the ABC +Corporation cell, and then removes the group from the Protection +Database. +

   % fs listacl /afs/abc.com/usr/terry
+   Access list for /afs/abc.com/usr/terry is
+   Normal permissions:
+     terry:friends rlik
+     system:anyuser l
+     terry rlidwka
+   % pts delete terry:friends
+   % fs listacl /afs/abc.com/usr/terry
+   Access list for /afs/abc.com/usr/terry is
+   Normal permissions:
+     -567 rlik
+     system:anyuser l
+     terry rlidwka
+

Leaving AFS IDs on ACLs serves no function, because the ID no longer +corresponds to an active user or group. Furthermore, if the ID is ever +assigned to a new user or group, then the new possessor of the ID gains access +that the owner of the directory actually intended for the previous +possessor. (Reusing AFS IDs is not recommended precisely for this +reason.) +

To remove obsolete AFS UIDs from ACLs, use the fs cleanacl +command. + + +

To clean obsolete AFS IDs from an ACL

Verify that you have the a (administer) permission +on each directory for which you are cleaning the ACL. If necessary, +issue the fs listacl command, which is fully described in Displaying ACLs. +
```
   % fs listacl [<dir/file path>]
+
```
+
Issue the fs cleanacl command to remove entries for obsolete +AFS IDs. +
```
   % fs cleanacl [<dir/file path>⁺]
+
```
+
where +
+
cl +
Is the shortest acceptable abbreviation of cleanacl. +
dir/file path +
Names each directory for which to clean the ACL. If this argument +names a file, its directory's ACL is cleaned. Omit this argument +to clean the current working directory's ACL. +
Specify the read/write path to each directory, to avoid the failure that +results when you attempt to change a read-only volume. By convention, +you indicate the read/write path 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 Rules of Mount Point Traversal. +
You can also use the following notation on its own or as part of a +pathname: +
+
. +
(A single period). If used by itself, cleans the current working +directory's ACL. +
.. +
(Two periods). If used by itself, cleans the ACL on the current +working directory's parent directory. +
* +
(The asterisk). Cleans the ACL of each of the subdirectories in the +current working directory. However, if you use the asterisk and there +are obsolete AFS IDs on any directory's ACL, the following error message +appears for every file in the directory: +
fs: 'filename': Not a directory +
+
+
+

If there are obsolete AFS IDs on a directory, the command interpreter +displays its cleaned ACL under the following header. +

   Access list for directory is now
+

If a directory's ACL has no obsolete AFS IDs on it, the following +message appears for each. +

   Access list for directory is fine.
+

How AFS Interprets the UNIX Mode Bits

+ + + +

Although AFS uses ACLs to protect file data rather than the mode bits that +UFS uses, it does not ignore the mode bits entirely. When you issue the +chmod command on an AFS file or directory, AFS changes the bits +appropriately. To change a file's mode bits, you must have the AFS +w (write) permission on the ACL of the file's +directory. To change a directory's mode bits, you must have the +d (delete), i (insert), and +l (lookup) permissions on its ACL. +

AFS also uses the UNIX mode bits as follows: +

It uses the initial bit to determine the element's type. This +is the bit that appears first in the output from the ls -l command +and shows the hyphen (-) for a file or the letter d for +a directory. +
It does not use any of the mode bits on a directory. +
For a file, the first (owner) set of bits interacts with the ACL entries +that apply to the file in the following way: +
- If the first r mode bit is not set, no one (including the +owner) can read the file, no matter what permissions they have on the +ACL. If the bit is set, users also need the r +(read) and l permissions on the ACL of the file's +directory to read the file. +
- If the first w mode bit is not set, no one (including the +owner) can modify the file. If the w bit is set, users also +need the w and l permissions on the ACL of the +file's directory to modify the file. +
- There is no ACL permission directly corresponding to the x mode +bit, but to execute a file stored in AFS, the user must also have the +r and l permissions on the ACL of the file's +directory. +
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd021.htm b/doc/html/AdminGuide/auagd021.htm new file mode 100644 index 0000000..55318fb --- /dev/null +++ b/doc/html/AdminGuide/auagd021.htm @@ -0,0 +1,416 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Managing Administrative Privilege

This chapter explains how to enable system administrators +and operators to perform privileged AFS operations. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + + + + + +
Display members of system:administrators group + pts membership +
Add user to system:administrators group + pts adduser +
Remove user from system:administrators group + pts removeuser +
Display ADMIN flag in Authentication Database entry + kas examine +
Set or remove ADMIN flag on Authentication Database entry + kas setfields +
Display users in UserList file + bos listusers +
Add user to UserList file + bos adduser +
Remove user from UserList file + bos removeuser +
+

An Overview of Administrative Privilege

+ + +

A fully privileged AFS system administrator has the following +characteristics: +

Membership in the cell's system:administrators +group. See Administering the system:administrators Group. +
The ADMIN flag on his or her entry in the cell's +Authentication Database. See Granting Privilege for kas Commands: the ADMIN Flag. +
Inclusion in the file /usr/afs/etc/UserList on the local disk +of each AFS server machine in the cell. See Administering the UserList File. +

This section describes the three privileges and explains why more than one +privilege is necessary. +
Note: Never grant any administrative privilege to the user anonymous, +even when a server outage makes it impossible to mutually authenticate. +If you grant such privilege, then any user who can access a machine in your +cell can issue privileged commands. The alternative solution is to put +the affected server machine into no-authentication mode and use the +-noauth flag available on many commands to prevent mutual +authentication attempts. For further discussion, see Managing Authentication and Authorization Requirements. +
+

The Reason for Separate Privileges

Often, a cell's administrators require full +administrative privileges to perform their jobs effectively. However, +separating the three types of privilege makes it possible to grant only the +minimum set of privileges that a given administrator needs to complete his or +her work. +

The system:administrators group privilege is perhaps the +most basic, and most frequently used during normal operation (when all the +servers are running normally). When the Protection Database is +unavailable due to machine or server outage, it is not possible to issue +commands that require this type of privilege. +

The ADMIN flag privilege is separate because of the extreme +sensitivity of the information in the Authentication Database, especially the +server encryption key in the afs entry. When the +Authentication Database is unavailable due to machine or server outage, it is +not possible to issue commands that require this type of privilege. +

The ability to issue privileged bos and vos command +is recorded in the /usr/afs/etc/UserList file on the local disk of +each AFS server machine rather than in a database, so that in case of serious +server or network problems administrators can still log onto server machines +and use those commands while solving the problem. +

Administering the system:administrators Group

+ + + + + + + +

The first type of AFS administrative privilege is membership . +Members of the system:administrators group in the Protection +Database have the following privileges: +

Permission to issue all pts commands, which are used to +administer the Protection Database. See Administering the Protection Database. +
Permission to issue the fs setvol and fs setquota +commands, which set the space quota on volumes as described in Setting and Displaying Volume Quota and Current Size. +
Implicit a (administer) and by default l +(lookup) permissions on the access control list (ACL) on every +directory in the cell's AFS filespace. Members of the group can +use the fs setacl command to grant themselves any other permissions +they require, as described in Setting ACL Entries. +
You can change the ACL permissions that the File Server on a given file +server machine implicitly grants to the members of the +system:administrators group for the data in volumes that it +houses. When you issue the bos create command to create and +start the fs process on the machine, include the +-implicit argument to the fileserver initialization +command. For syntax details, see the fileserver reference +page in the IBM AFS Administration Reference. You can grant +additional permissions, or remove the l permission. However, +the File Server always implicitly grants the a permission to +members of the group, even if you set the value of the -implicit +argument to none. +

+ + + + +

To display the members of the system:administrators group

Issue the pts membership command to display the +system:administrators group's list of members. +Any user can issue this command as long as the first privacy flag on the +system:administrators group's Protection Database entry +is not changed from the default value of uppercase S. +
```
   % pts membership system:administrators
+
```
+
where m is the shortest acceptable abbreviation of +membership. +

To add users to the system:administrators group

+ + + + +

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts adduser group to add one or more users. +
```
   % pts adduser -user <user name>⁺ -group system:administrators
+
```
+
where +
+
ad +
Is the shortest acceptable abbreviation of adduser. +
-user +
Names each user to add to the system:administrators +group. +
+

To remove users from the system:administrators group

+ + + + +

Verify that you belong to the system:administrators +group. If necessary, issue the pts membership command, which +is fully described in To display the members of the system:administrators group. +
```
   % pts membership system:administrators
+   
+
```
+
Issue the pts removeuser command to remove one or more +users. +
```
   % pts removeuser -user <user name>⁺ -group system:administrators
+
```
+
where +
+
rem +
Is the shortest acceptable abbreviation of removeuser. +
-user +
Names each user to remove from the system:administrators +group. +
+

Granting Privilege for kas Commands: the ADMIN Flag

+ +

Administrators who have the ADMIN flag on their Authentication +Database entry can issue all kas commands, which enable them to +administer the Authentication Database. + + + +

To check if the ADMIN flag is set

+ + + + +

Issue the kas examine command to display an entry +from the Authentication Database. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UFS) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin_username argument (here +abbreviated to -admin) to name a user identity that has the +ADMIN flag on its Authentication Database entry. +
```
   % kas examine <name of user>   \
+                 -admin  <admin principal to use for authentication>
+   Administrator's (admin_user) password: admin_password
+
```
+
where +
+
e +
Is the shortest acceptable abbreviation of examine. +
name of user +
Names the entry to display. +
-admin +
Names an administrative account with the ADMIN flag on its +Authentication Database entry, such as the admin account. +The password prompt echoes it as admin_user. Enter the +appropriate password as admin_password. +
+

If the ADMIN flag is turned on, it appears on the first line, as +in this example: +

   % kas e terry -admin admin
+   Administrator's (admin) password: admin_password
+   User data for terry (ADMIN)
+     key version is 0, etc...
+

+ + + + + + +

To set or remove the ADMIN flag

Issue the kas setfields command to turn on the ADMIN +flag in an Authentication Database entry. +
The Authentication Server performs its own authentication rather than +accepting your existing AFS token. By default, it authenticates your +local (UNIX) identity, which possibly does not correspond to an AFS-privileged +administrator. Include the -admin argument to name an +identity that has the ADMIN flag on its Authentication Database +entry. To verify that an entry has the flag, issue the kas +examine command as described in To check if the ADMIN flag is set. +
The following command appears on two lines only for legibility. +
```
    % kas setfields <name of user>  {ADMIN |  NOADMIN} \  
+                   -admin <admin principal to use for authentication>  
+    Administrator's (admin_user) password: admin_password
+
```
+
where +
+
sf +
Is an alias for setfields (and setf is the shortest +acceptable abbreviation). +
name of user +
Names the entry for which to set or remove the ADMIN +flag. +
ADMIN | NOADMIN +
Sets or removes the ADMIN flag, respectively. +
-admin +
Names an administrative account with the ADMIN flag on its +Authentication Database entry, such as the admin account. +The password prompt echoes it as admin_user. Enter the +appropriate password as admin_password. +
+

Administering the UserList File

+ +

Inclusion in the file /usr/afs/etc/UserList on the local disk of +each AFS server machine enables an administrator to issue commands from the +indicated suites. +

The bos commands enable the administrator to manage server +processes and the server configuration files that define the cell's +database server machines, server encryption keys, and privileged users. +See Administering Server Machines and Monitoring and Controlling Server Processes. +
The vos commands enable the administrator to manage volumes and +the Volume Location Database (VLDB). See Managing Volumes. +
The backup commands enable the administrator to use the AFS +Backup System to copy data to permanent storage. See Configuring the AFS Backup System and Backing Up and Restoring AFS Data. +

+ + + + + + + + + + +

Although each AFS server machine maintains a separate copy of the file on +its local disk, it is conventional to keep all copies the same. It can +be confusing for an administrator to have the privilege on some machines but +not others. + +

If your cell runs the United States edition of AFS and uses the Update +Server to distribute the contents of the system control machine's +/usr/afs/etc directory, then edit only the copy of the +UserList file stored on the system control machine. If you +have forgotten which machine is the system control machine, see The Four Roles for File Server Machines. +

If your cell runs the international edition of AFS, or does not use a +system control machine, then you must edit the UserList file on +each server machine individually. +

To avoid making formatting errors that can result in performance problems, +never edit the UserList file directly. Instead, use the +bos adduser or bos removeuser commands as described in +this section. + + + + +

To display the users in the UserList file

Issue the bos listusers command to display the contents of the +/usr/afs/etc/UserList file. +
```
   % bos listusers <machine name>
+
```
+
where +
+
listu +
Is the shortest acceptable abbreviation of listusers. +
machine name +
Names an AFS server machine. In the normal case, any machine is +acceptable because the file is the same on all of them. +
+

To add users to the UserList file

+ + + + +

Verify you are listed in the /usr/afs/etc/UserList file. +If not, you must have a qualified administrator add you before you can add +entries to it yourself. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos adduser command to add one or more users to the +UserList file. +
```
   % bos adduser <machine name> <user names>⁺
+
```
+
where +
+
addu +
Is the shortest acceptable abbreviation of adduser. +
machine name +
Names the system control machine if you use the Update Server to +distribute the contents of the /usr/afs/etc directory (possible +only in cells running the United States edition of AFS). By default, it +can take up to five minutes for the Update Server to distribute the changes, +so newly added users must wait that long before attempting to issue privileged +commands. +
If you are running the international edition of AFS, or do not use the +Update Server, repeat the command, substituting the name of each AFS server +machine for machine name in turn. +
user names +
Specifies the username of each administrator to add to the +UserList file. +
+

To remove users from the UserList file

+ + + + +

Verify you are listed in the /usr/afs/etc/UserList file. +If not, you must have a qualified administrator add you before you can remove +entries from it yourself. If necessary, issue the bos +listusers command, which is fully described in To display the users in the UserList file. +
```
   % bos listusers <machine name>
+
```
+
Issue the bos removeuser command to remove one or more users +from the UserList file. +
```
   % bos removeuser <machine name> <user names>⁺
+
```
+
where +
+
removeu +
Is the shortest acceptable abbreviation of removeuser. +
machine name +
Names the system control machine if you use the Update Server to +distribute the contents of the /usr/afs/etc directory (possible +only in cells running the United States edition of AFS). By default, it +can take up to five minutes for the Update Server to distribute the change, so +newly removed users can continue to issue privileged commands during that +time. +
If you are running the international edition of AFS, or do not use the +Update Server, repeat the command, substituting the name of each AFS server +machine for machine name in turn. +
user names +
Specifies the username of each administrator to add to the +UserList file. +
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd022.htm b/doc/html/AdminGuide/auagd022.htm new file mode 100644 index 0000000..d1ca3a6 --- /dev/null +++ b/doc/html/AdminGuide/auagd022.htm @@ -0,0 +1,859 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Appendix A. Managing the NFS/AFS Translator

+ + +

The NFS^{^(R)}/AFS^{^(R)} Translator enables users +working on NFS client machines to access, create and remove files stored in +AFS. This chapter assumes familiarity with both NFS and AFS. +

Summary of Instructions

This chapter explains how to perform the following tasks by +using the indicated commands: +
+ + + + + +
Mount directory on translator machine + mount +
Examine value of @sys variable + fs sysname +
Enable/disable reexport of AFS, set other parameters + fs exportafs +
Assign AFS tokens to user on NFS client machine + knfs +
+

Overview

The NFS/AFS Translator enables users on NFS client machines +to access the AFS filespace as if they are working on an AFS client machine, +which facilitates collaboration with other AFS users. +

An NFS/AFS translator machine (or simply translator +machine) is a machine configured as both an AFS client and an NFS +server: +

Its AFS client functionality enables it to access the AFS +filespace. The Cache Manager requests and caches files from AFS file +server machines, and can even maintain tokens for NFS users, if you have made +the configuration changes that enable NFS users to authenticate with +AFS. +
Its NFS server functionality makes it possible for the translator machine +to export the AFS filespace to NFS client machines. When a user on an +NFS client machine mounts the translator machine's /afs +directory (or one of its subdirectories, if that feature is enabled), access +to AFS is immediate and transparent. The NFS client machine does not +need to run any AFS software. +

Enabling Unauthenticated or Authenticated AFS Access

By configuring the translation environment appropriately, +you can provide either unauthenticated or authenticated access to AFS from NFS +client machines. The sections of this chapter on configuring translator +machines, NFS client machines, and AFS user accounts explain how to configure +the translation environment appropriately. +

If you configure the environment for unauthenticated access, the AFS File +Server considers the NFS users to be the user anonymous. +They can access only those AFS files and directories for which the access +control list (ACL) extends the required permissions to the +system:anyuser group. They can issue only those AFS +commands that do not require privilege, and then only if their NFS client +machine is a system type for which AFS binaries are available and accessible +by the system:anyuser group. Such users presumably do +not have AFS accounts. +
If you configure the environment for authenticated access, you must create +entries in the AFS Authentication and Protection Databases for the NFS +users. The authentication procedure they use depends on whether the NFS +client machine is a supported system type (one for which AFS binaries are +available): +
- If AFS binaries are available for the NFS client machine, NFS users can +issue the klog command on the NFS client machine. They can +access the filespace and issue AFS commands to the same extent as +authenticated users working on AFS client machines. +
- If AFS binaries are not available for the NFS client machine, NFS users +must establish a connection with the translator machine (using the +telnet utility, for example) and then issue the klog and +knfs commands on the translator machine to make its Cache Manager +use the tokens correctly while users work on the NFS client. They can +access the AFS filespace as authenticated users, but cannot issue AFS +commands. For instructions, see Authenticating on Unsupported NFS Client Machines. +
+

Setting the AFSSERVER and AFSCONF Environment Variables

If you wish to enable your NFS users to issue AFS commands, +you must define the AFSSERVER and AFSCONF environment variables in their +command shell. This section explains the variables' function and +outlines the various methods for setting them. +

Issuing AFS commands also requires that the NFS client machine is a +supported system type (one for which AFS binaries are available and +accessible). Users working on NFS client machines of unsupported system +types can access AFS as authenticated users, but they cannot issue AFS +commands. It is not necessary to define the AFSSERVER and AFSCONF +variables for such users. For instructions on using the knfs +command to obtain authenticated access on unsupported system types, see Authenticating on Unsupported NFS Client Machines. + +

The AFSSERVER Variable

The AFSSERVER variable designates the AFS client machine +that performs two functions for NFS clients: +

It acts as the NFS client's remote executor by executing +AFS-specific system calls on its behalf, such as those invoked by the +klog and tokens commands and by many commands in the AFS +suites. +
Its stores the tokens that NFS users obtain when they authenticate with +AFS. This implies that the remote executor machine and the translator +machine must be the same if the user needs authenticated access to AFS. +

The choice of remote executor most directly affects commands that display +or change Cache Manager configuration, such as the fs +getcacheparms, fs getcellstatus, and fs setcell +commands. When issued on an NFS client, these commands affect the Cache +Manager on the designated remote executor machine. (Note, however, that +several such commands require the issuer to be logged into the remote +executor's local file system as the local superuser +root. The ability of NFS client users to log in as +root is controlled by NFS, not by the NFS/AFS Translator, so +setting the remote executor properly does not necessarily enable users on the +NFS client to issue such commands.) +

The choice of remote executor is also relevant for AFS commands that do not +concern Cache Manager configuration but rather have the same result on every +machine, such as the fs commands that display or set ACLs and +volume quota. These commands take an AFS path as one of their +arguments. If the Cache Manager on the remote executor machine mounts +the AFS filespace at the /afs directory, as is conventional for AFS +clients, then the pathname specified on the NFS client must begin with the +string /afs for the Cache Manager to understand it. This +implies that the remote executor must be the NFS client's primary +translator machine (the one whose /afs directory is mounted at +/afs on the NFS client). + + +

The AFSCONF Variable

The AFSCONF environment variable names the directory that houses the +ThisCell and CellServDB files to use when running AFS +commands issued on the NFS client machine. As on an AFS client, these +files determine the default cell for command execution. +

For predictable performance, it is best that the files in the directory +named by the AFSCONF variable match those in the /usr/vice/etc +directory on the translator machine. If your cell has an AFS directory +that serves as the central update source for files in the +/usr/vice/etc directory, it is simplest to set the AFSCONF variable +to refer to it. In the conventional configuration, this directory is +called /afs/cellname/common/etc. +

Setting Values for the Variables

To learn the values of the AFSSERVER and AFSCONF variables, AFS command +interpreters consult the following three sources in sequence: +

The current command shell's environment variable definitions +
The .AFSSERVER or .AFSCONF file in the +issuer's home directory +
The /.AFSSERVER or /.AFSCONF file in +the NFS client machine's root (/) directory. If the +client machine is diskless, its root directory can reside on an NFS server +machine. +

(Actually, before consulting these sources, the NFS client looks for the +CellServDB and ThisCell files in its own +/usr/vice/etc directory. If the directory exists, the NFS +client does not use the value of the AFSCONF variable. However, the +/usr/vice/etc directory usually exists only on AFS clients, not NFS +clients.) +

As previously detailed, correct performance generally requires that the +remote executor machine be the NFS client's primary translator machine +(the one whose /afs directory is mounted at the /afs +directory on the NFS client). The requirement holds for all users +accessing AFS from the NFS client, so it is usually simplest to create the +.AFSSERVER file in the NFS client's root +directory. The main reason to create the file in a user's home +directory or to set the AFSSERVER environment variable in the current command +shell is that the user needs to switch to a different translator machine, +perhaps because the original one has become inaccessible. +

Similarly, it generally makes sense to create the +.AFSCONF file in the NFS client's root +directory. Creating it in the user's home directory or setting the +AFSCONF environment variable in the current command shell is useful mostly +when there is a reason to specify a different set of database server machines +for the cell, perhaps in a testing situation. +

Delayed Writes for Files Saved on NFS Client Machines

+ + + + + + + +

When an application running on an AFS client machine issues the +close or fsync system call on a file, the Cache Manager +by default performs a synchronous write of the data to the File Server. +(For further discussion, see AFS Implements Save on Close and Enabling Asynchronous Writes.) +

To avoid degrading performance for the AFS users working on a translator +machine, AFS does not perform synchronous writes for applications running on +the translator machine's NFS clients. Instead, one of the Cache +Manager daemons (the maintenance daemon) checks every 60 seconds +for chunks in the cache that contain data saved on NFS clients, and writes +their contents to the File Server. This does not guarantee that data +saved on NFS clients is written to the File Server within 60 seconds, but only +that the maintenance daemon checks for and begins the write of data at that +interval. +

Furthermore, AFS always ignores the fsync system call as issued +on an NFS client. The call requires an immediate and possibly +time-consuming response from the File Server, which potentially causes delays +for other AFS clients of the File Server. NFS version 3 automatically +issues the fsync system call directly after the close +call, but the Cache Manager ignores it and handles the operation just like a +regular close. +

The delayed write mechanism means that there is usually a delay between the +time when an NFS application issues the close or fsync +system call on a file and the time when the changes are recorded at the File +Server, which is when they become visible to users working on other AFS client +machines (either directly or on its NFS clients). The delay is likely +to be longer than for files saved by users working directly on an AFS client +machine. +

The exact amount of delay is difficult to predict. The NFS protocol +itself allows a standard delay before saved data must be transferred from the +NFS client to the NFS server (the translator machine). The modified +data remains in the translator machine's AFS client cache until the +maintenance daemon's next scheduled check for such data, and it takes +additional time to transfer the data to the File Server. The +maintenance daemon uses a single thread, so there can be additional delay if +it takes more than 60 seconds to write out all of the modified NFS +data. That is, if the maintenance daemon is still writing data at the +time of the next scheduled check, it cannot notice any additional modified +data until the scheduled time after it completes the long write +operation. +

The Cache Manager's response to the write system call is +the same whether it is issued on an AFS client machine or on an NFS client of +a translator machine: it records the modifications in the local AFS +client cache only. +

Configuring NFS/AFS Translator Machines

To act as an NFS/AFS translator machine, a machine must +configured as follows: +

It must be an AFS client. Many system types supported as AFS +clients can be translator machines. To learn about possible +restrictions in a specific release of AFS, see the IBM AFS Release +Notes. +
It must be an NFS server. The appropriate number of NFS server +daemons (nfsd and others) depends on the anticipated NFS client +load. +
It must export the local directory on which the AFS filespace is mounted, +/afs by convention. +

If users on a translator machine's NFS clients are to issue AFS +commands, the translator machine must also meet the requirements discussed in Configuring the Translator Machine to Accept AFS Commands. +

Loading NFS and AFS Kernel Extensions

The AFS distribution for system types that can act as NFS/AFS +Translator machines usually includes two versions of the AFS kernel extensions +file, one for machines where the kernel supports NFS server functionality, and +one for machines not using NFS (the latter AFS kernel extensions file +generally has the string nonfs in its name). A translator +machine must use the NFS-enabled version of the AFS extensions file. On +some system types, you select the appropriate file by moving it to a certain +location, whereas on other system types you set a variable that results in +automatic selection of the correct file. See the instructions in the +IBM AFS Quick Beginnings for incorporating AFS into the kernel on +each system type. +

On many system types, NFS is included in the kernel by default, so it is +not necessary to load NFS kernel extensions explicitly. On system types +where you must load NFS extensions, then in general you must load them before +loading the AFS kernel extensions. The IBM AFS Quick +Beginnings describes how to incorporate the AFS initialization script +into a machine's startup sequence so that it is ordered correctly with +respect to the script that handles NFS. +

In addition, the AFS extensions must be loaded into the kernel before the +afsd command runs. The AFS initialization script included in +the AFS distribution correctly orders the loading and afsd +commands. +

Configuring the Translator Machine to Accept AFS Commands

For users working on a translator machine's NFS +clients to issue AFS commands, the -rmtsys flag must be included on +the afsd command which initializes the translator machine's +Cache Manager. The flag starts an additional daemon (the remote +executor daemon), which executes AFS-specific system calls on behalf of +NFS clients. For a discussion of the implications of NFS users issuing +AFS commands, see Setting the AFSSERVER and AFSCONF Environment Variables. +

The instructions in the IBM AFS Quick Beginnings for configuring +the Cache Manager explain how to add options such as the -rmtsys +flag to the afsd command in the AFS initialization script. +On many system types, it is simplest to list the flag on the line in the +script that defines the OPTIONS variable. The remote executor daemon +does not consume many resources, so it is simplest to add it to the +afsd command on every translator machine, even if not all users on +the machine's NFS clients issue AFS commands. +

Controlling Optional Translator Features

After an AFS client machine is configured as a translator +machine, it by default exports the AFS filespace to NFS clients. You +can disable and reenable translator functionality by using the fs +exportafs command's -start argument. The +command's other arguments control other aspects of translator +behavior. +

The -convert argument controls whether the second and third +(group and other) sets of UNIX mode bits on an AFS file +or directory being exported to NFS are set to match the first +(owner) mode bits. By default, the mode bits are set to +match. +
Unlike AFS, NFS uses all three sets of mode bits when determining whether a +user can read or write a file, even one stored in AFS. Some AFS files +possibly do not have any group and other mode bits +turned on, because AFS uses only the owner bits in combination with +the ACL on the file's directory. If only the owner mode +bits are set, NFS allows only the file's owner of the file to read or +write it. Setting the -convert argument to the value +on enables other users to access the file in the same manner as the +owner. Setting the value off preserves the mode bits set on +the file as stored in AFS. +

The -uidcheck argument controls whether tokens can be assigned +to an NFS user whose local UID on the NFS client machine differs from the +local UID associated with the tokens on the translator machine. By +default, this is possible. +

If you turn on UID checking by setting the value on, then tokens +can be assigned only to an NFS user whose local UID matches the local UID of +the process on the translator machine that is assigning the tokens. One +consequence is that there is no point in including the -id argument +to the knfs command: the only acceptable value is the local +UID of the command's issuer, which is the value used when the +-id argument is omitted. Requiring matching UIDs in this way +is effective only when users have the same local UID on the translator machine +as on NFS client machines. In that case, it guarantees that users +assign their tokens only to their own NFS sessions. For instructions, +see Authenticating on Unsupported NFS Client Machines. +
Note: Turning on UID checking also prevents users on supported NFS clients from +using the klog command to authenticate on the NFS client +directly. They must authenticated and use the knfs command +on the translator machine instead. This is because after the +klog command interpreter obtains the token on the NFS client, it +passes it to the Cache Manager's remote executor daemon, which makes the +system call that stores the token in a credential structure on the translator +machine. The remote executor generally runs as the local superuser +root, so in most cases its local UID (normally zero) does not match +the local UID of the user who issued the klog command on the NFS +client machine. +
On the other hand, although using the knfs command instead of +the klog command is possibly less convenient for users, it +eliminates a security exposure: the klog command interpreter +passes the token across the network to the remote executor daemon in clear +text mode. +
+

If you disable UID checking by assigning the value off , the +issuer of the knfs command can assign tokens to a user who has a +different local UID on the NFS client machine, such as the local superuser +root. Indeed, more than one issuer of the knfs +command can assign tokens to the same user on the NFS client machine. +Each time a different user issues the knfs command with the same +value for the -id argument, that user's tokens overwrite the +existing ones. This can result in unpredictable access for the NFS +user. +

The -submounts argument controls whether users on the NFS +client can mount AFS directories other than the top-level /afs +directory. By default, the translator does not permit these +submounts. +
Submounts can be useful in a couple of circumstances. If, for +example, NFS users need to access their own AFS home directories only, then +creating a submount to it eliminates the need for them to know or enter the +complete path. Similarly, you can use a submount to prevent users from +accessing parts of the filespace higher in the AFS hierarchy than the +submount. +

To configure an NFS/AFS translator machine

The following instructions configure the translator to enable users to +issue AFS commands. Omit Step 6 if you do not want to enable this functionality. +

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Configure the NFS/AFS translator machine as an NFS server, if it is not +already. Follow the instructions provided by your NFS supplier. +The appropriate number of NFS server daemons (such as nfsd) depends +on the number of potential NFS clients. +
Configure the NFS/AFS translator machine as an AFS client, if it is not +already. For the most predictable performance, the translator +machine's local copies of the /usr/vice/etc/CellServDB and +/usr/vice/etc/ThisCell files must be the same as on other client +machines in the cell. +
Modify the file that controls mounting of directories +on the machine by remote NFS clients. +
- On systems that use the /etc/exports file, edit it to enable +export of the /afs directory to NFS clients. You can list +the names of specific NFS client machines if you want to provide access only +to certain users. For a description of the file's format, see the +NFS manual page for exports(5). +
  The following example enables any NFS client machine to mount the +machine's /afs, /usr, and /usr2 +directories: +
```
   /afs
+   /usr
+   /usr2
+
```
  + + +
- On system types that use the share command, edit the +/etc/dfs/dfstab file or equivalent to include share +instructions that enable remote mounts of the /afs +directory. Most distributions include the binary as +/usr/sbin/share. The following example commands enable +remote mounts of the root ( / ) and /afs +directories. To verify the correct syntax, consult the manual page for +the share command. +
```
   share -F nfs -o rw -d "root" /
+   share -F nfs -o rw -d "afs gateway" /afs
+
```
  +
+
Edit the machine's AFS initialization file to invoke the standard +UNIX exportfs command after the afsd program +runs. On some system types, the modifications you made in Step 4 are not enough to enable exporting the AFS filespace +via the /afs directory, because the resulting configuration changes +are made before the afsd program runs during machine +initialization. Only after the afsd program runs does the +/afs directory become the mount point for the entire AFS +filespace; before, it is a local directory like any other. +
Modify the afsd command in the AFS initialization +file to include the -rmtsys flag. +
For system types other than IRIX, the instructions in the IBM AFS +Quick Beginnings for configuring the Cache Manager explain how to add +the -rmtsys flag, for example by adding it to the line in the +script that defines the value for the OPTIONS variable. +
On IRIX systems, the AFS initialization script automatically adds the +-rmtsys flag if you have activated the afsxnfs +configuration variable as instructed in the IBM AFS Quick +Beginnings instructions for incorporating AFS extensions into the +kernel. If the variable is not already activated, issue the following +command. +
```
   
+   # /etc/chkconfig  -f  afsxnfs  on
+
```
+
(Optional) Depending on the number of NFS clients you expect +this machine to serve, it can be beneficial to add other arguments to the +afsd command in the machine's initialization file, such as the +-daemons argument to set the number of background daemons. +See Administering Client Machines and the Cache Manager and the afsd reference page in the IBM AFS +Administration Reference. +
Reboot the machine. On many system types, the appropriate command +is shutdown; consult your operating system +administrator's guide. +
```
   # shutdown appropriate_options
+
```
+

+ + +

To disable or enable Translator functionality, or set optional features

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Issue the fs exportafs command. +
```
   # fs exportafs nfs [-start {on | off}} ]  [-convert {on | off}]   
+                      [-uidcheck {on | off}]   [-submounts {on | off}] 
+
```
+
+
-start +
Disables translator functionality if the value is off or +reenables it if the value is on. Omit this argument to +display the current setting of all parameters set by this command. +
-convert +
Controls the setting of the second and third (group and +other) sets of UNIX mode bits on AFS files and directories as +exported to NFS clients If the value is on, they are set to match +the owner mode bits. If the value is off, the +bits are not changed. If this argument is omitted, the default value is +on. +
-uidcheck +
Controls whether issuers of the knfs command can specify a +value for its -id argument that does not match their AFS UID: +
- If the value is on, the value of the -id argument +must match the issuer's local UID. +
- If the value is off, the issuer of the knfs command +can use the -id argument to assign tokens to a user who has a +different local UID on the NFS client machine, such as the local superuser +root. +
+
If this argument is omitted, the default value is off. +
-submounts +
Controls whether the translator services an NFS mount of any directory in +the AFS filespace other than the top-level /afs directory. +If the value is on, such submounts are allowed. If the value +is off, only mounts of the /afs directory are allowed. If +this argument is omitted, the default value is off. +
+

Configuring NFS Client Machines

Any NFS client machine that meets the following requirements +can access files in AFS via the NFS/AFS Translator. It does not need to +be configured as an AFS client machine. +

It must NFS-mount a translator machine's /afs directory on +a local directory, which by convention is also called /afs. +The following instructions explain how to add the mount command to +the NFS client machine's /etc/fstab file or equivalent. +
+
The directory on which an NFS client mounts the translator's +machine's /afs directory can be called something other than +/afs. For instance, to make it easy to switch to another +translator machine if the original one becomes inaccessible, you can mount +more than one translator machine's /afs directory. Name +the mount /afs for the translator machine that you normally use, +and use a different name the mount to each alternate translator +machine. +
Mounting the AFS filespace on a directory other than /afs +introduces another requirement, however: when issuing a command that +takes an AFS pathname argument, you must specify the full pathname, starting +with /afs, rather than a relative pathname. Suppose, for +example, that a translator machine's AFS filespace is mounted at +/afs2 on an NFS client machine and you issue the following command +to display the ACL on the current working directory, which is in AFS: +
```
   % fs listacl .
+
```
+
The fs command interpreter on the NFS client must construct a +full pathname before passing the request to the Cache Manager on the +translator machine. The AFS filespace is mounted at /afs2, +so the full pathname starts with that string. However, the Cache +Manager on the translator cannot find a directory called /afs2, +because its mount of the AFS filespace is called /afs. The +command fails. To prevent the failure, provide the file's complete +pathname, starting with the string /afs. +
It must run an appropriate number of NFS client biod daemons, +which improve performance by handling pre-reading and delayed writing. +Most NFS vendors recommend running four such daemons, and most NFS +initialization scripts start them automatically. Consult your NFS +documentation. +

To enable users to issue AFS commands, the NFS client machine must also be +a supported system type (one for which AFS binaries are available) and able to +access the AFS command binaries. The IBM AFS Release Notes +list the supported system types in each release. +

In addition, the AFSSERVER and AFSCONF environment variables must be set +appropriately, as discussed in Setting the AFSSERVER and AFSCONF Environment Variables. +

To configure an NFS client machine to access AFS

Note:

The following instructions enable NFS users to issue AFS commands. +Omit Step 5 and Step 6 if you do not want to enable this +functionality. +

Become the local superuser root on the machine, if you are not +already, by issuing the su command. +
```
   % su root
+   Password: root_password
+
```
+
Configure the machine as an NFS client machine, if it is not +already. Follow the instructions provided by your NFS vendor. +The number of NFS client (biod) daemons needs to be appropriate for +the expected load on this machine. The usual recommended number is +four. +
Create a directory called /afs on the machine, if one does not +already exist, to act as the mount point for the translator machine's +/afs directory. It is acceptable to use other names, but +doing so introduces the limitation discussed in the introduction to this +section. +
```
   # mkdir /afs
+
```
+ + +

Modify the machine's file systems registry file +(/etc/fstab or equivalent) to include a command that mounts a +translator machine's /afs directory. To verify the +correct syntax of the mount command, see the operating +system's mount(5) manual page. The following example +includes options that are appropriate on many system types. +

   mount -o hard,intr,timeo=300  translator_machine:/afs /afs
+

where +

hard +

Indicates that the NFS client retries NFS requests until the NFS server +(translator machine) responds. When using the translator, file +operations possibly take longer than with NFS alone, because they must also +pass through the AFS Cache Manager. With a soft mount, a delayed +response from the translator machine can cause the request to abort. +Many NFS versions use hard mounts by default; if your version does not, +it is best to add this option. +

intr +

Enables the user to use a keyboard interrupt signal (such as +<Ctrl-c>) to break the mount when the translator machine is +inaccessible. Include this option only if the hard option is +used, in which case the connection does not automatically break off when a +translator machine goes down. +

timeo +

Sets the maximum time (in tenths of seconds) the translator can take to +respond to the NFS client's request before the client considers the +request timed out. With a hard mount, setting this option to a high +number like 300 reduces the number of error messages like the following, which +are generated when the translator does not respond immediately. +

   NFS server translator is not responding, still trying
+

With a soft mount, it reduces the number of actual errors returned on +timed-out requests. +

translator_machine +

Specifies the fully-qualified hostname of the translator machine whose +/afs directory is to be mounted on the client machine's +/afs directory. +

Note: To mount the translator machine's /afs directory onto a +directory on the NFS client other than /afs, substitute the +alternate directory name for the second instance of /afs in the +mount command. +

(Optional) If appropriate, create the +/.AFSSERVER file to set the AFSSERVER environment variable +for all of the machine's users. For a discussion, see Setting the AFSSERVER and AFSCONF Environment Variables. Place a single line in the file, specifying the +fully-qualified hostname of the translator machine that is to serve as the +remote executor. To enable users to issue commands that handle tokens, +it must be the machine named as translator_machine in Step 4. +
(Optional) If appropriate, create the +/.AFSCONF file to set the AFSCONF environment variable for +all of the machine's users. For a discussion, see Setting the AFSSERVER and AFSCONF Environment Variables. Place a single line in the file, specifying the name +of the directory where the CellServDB and ThisCell files +reside. If you use a central update source for these files (by +convention, /afs/cellname/common/etc), name it +here. +

Configuring User Accounts

There are no requirements for NFS users to access AFS as +unauthenticated users. To take advantage of more AFS functionality, +however, they must meet the indicated requirements. +

To access AFS as authenticated users, they must of course authenticate +with AFS, which requires an entry in the Protection and Authentication +Databases. +
To create and store files, they need the required ACL permissions. +If you are providing a home directory for storage of personal files, it is +conventional to create a dedicated volume and mount it at the user's home +directory location in the AFS filespace. +
To issue AFS commands, they must meet several additional +requirements: +
- They must be working on an NFS client machine of a supported system type +and from which the AFS command binaries are accessible. +
- Their command shell must define values for the AFSSERVER and AFSCONF +environment variables, as described in Setting the AFSSERVER and AFSCONF Environment Variables. It is often simplest to define the variables by +creating /.AFSSERVER and /.AFSCONF file in +the NFS client machine's root directory, but you can also either set the +variables in each user's shell initialization file +(.cshrc or equivalent), or create files called +.AFSSERVER and .AFSCONF in each +user's home directory. +
- They must have an entry in the AFS Protection and Authentication +Databases, so that they can authenticate if the command requires AFS +privilege. Other commands instead require assuming the local +root identity on the translator machine; for further +discussion, see The AFSSERVER Variable. +
- Their PATH environment variable must include the pathname to the +appropriate AFS binaries. If a user works on NFS client machines of +different system types, include the @sys variable in the pathname +rather than an actual system type name. +
+

To configure a user account for issuing AFS commands

Create entries for the user in the Protection and Authentication +Databases, or create a complete AFS account. See the instructions for +account creation in Creating and Deleting User Accounts with the uss Command Suite or Administering User Accounts. +
Modify the user's PATH environment variable to include the +pathname of AFS binaries, such as +/afs/cellname/sysname/usr/afsws/bin. +If the user works on NFS client machines of different system types, +considering replacing the specific sysname value with the +@sys variable. The PATH variable is commonly defined in a +login or shell initialization file (such as the .login or +.cshrc file). +
(Optional) Set the AFSSERVER and AFSCONF environment variables +if appropriate. This is required if the NFS client machines on which +the user works do not have the /.AFSSERVER and +/.AFSCONF files in their root directories, or if you want +user-specific values to override those settings. +
Either define the variables in the user's login or shell +initialization file, or create the files .AFSSERVER and +.AFSCONF files in the user's home directory. +
For the AFSSERVER variable, specify the fully-qualified hostname of the +translator machine that is to serve as the remote executor. For the +AFSCONF variable, specify the name of the directory where the +CellServDB and ThisCell files reside. If you use +a central update source for these files (by convention, +/afs/cellname/common/etc), name it here. +
If the pathname you defined in Step 2 includes the @sys variable, instruct users to +check that their system name is defined correctly before they issue AFS +commands. They issue the following command: +
```
   % fs sysname
+
```
+

Authenticating on Unsupported NFS Client Machines

The knfs command enables users to authenticate +with AFS when they are working on NFS clients of unsupported system types +(those for which AFS binaries are not available). This enables such +users to access the AFS file tree to the same extent as any other AFS +user. They cannot, however, issue AFS commands, which is possible only +on NFS client machines of supported system types. +

To authenticate on an unsupported system type, establish a connection to +the translator machine (using a facility such as telnet), and issue +the klog command to obtain tokens for all the cells you wish to +contact during the upcoming NFS session. Then issue the knfs +command, which stores the tokens in a credential structure associated with +your NFS session. The Cache Manager uses the tokens when performing AFS +access requests that originate from your NFS session. +

More specifically, the credential structure is identified by a process +authentication group (PAG) number associated with a particular local UID on a +specific NFS client machine. By default, the NFS UID recorded in the +credential structure is the same as your local UID on the translator +machine. You can include the -id argument to specify an +alternate NFS UID, unless the translator machine's administrator has used +the fs exportafs command's -uidcheck argument to +enable UID checking. In that case, the value of the -id +argument must match your local UID on the translator machine (so there is not +point to including the -id argument). Enforcing matching +UIDs prevents someone else from placing their tokens in your credential +structure, either accidentally or on purpose. However, it means that +your cell's administrators must set your local UID on the NFS client to +match your local UID on the translator machine. It also makes it +impossible to authenticate by issuing the klog command on supported +NFS clients, meaning that all NFS users must use the knfs +command. See Controlling Optional Translator Features. +

After issuing the knfs command, you can begin working on the NFS +client with authenticated access to AFS. When you are finished working, +it is a good policy to destroy your tokens by issuing the knfs +command on the translator machine again, this time with the -unlog +flag. This is simpler if you have left the connection to the translator +machine open, but you can always establish a new connection if you closed the +original one. +

If your NFS client machine is a supported system type and you wish to issue +AFS commands on it, include the -sysname argument to the +knfs command. The remote executor daemon on the translator +machine substitutes its value for the @sys variable in pathnames +when executing AFS commands that you issue on the NFS client machine. +If your PATH environment variable uses the @sys variable in the +pathnames for directories that house AFS binaries (as recommended), then +setting this argument enables the remote executor daemon to access the AFS +binaries appropriate for your NFS client machine even if its system type +differs from the translator machine's. +

If you do not issue the knfs command (or the klog +command on the NFS client machine itself, if it is a supported system type), +then you are not authenticated with AFS. For a description of +unauthenticated access, see Enabling Unauthenticated or Authenticated AFS Access. + + +

To authenticate using the knfs command

Log on to the relevant translator machine, either on the console or +remotely by using a program such as telnet. +
Obtain tokens for every cell you wish to access while working on the NFS +client. AFS-modified login utilities acquire a token for the translator +machine's local cell by default; use klog command to +obtain tokens for other cells if desired. +
Issue the knfs command to create a credential structure in the +translator machine's kernel memory for storing the tokens obtained in the +previous step. Include the -id argument to associate the +structure with a UID on the NFS client that differs from your local UID on the +translator machine. This is possible unless the translator +machine's administrator has enabled UID checking on the translator +machine; see Controlling Optional Translator Features. If the NFS client machine is a supported system type +and you wish to issue AFS commands on it, include the -sysname +argument to specify its system type. +
```
   % knfs -host <host name>  [-id <user ID (decimal)>]  [-sysname  <host's '@sys' value>]
+
```
+
where +
+
-host +
Specifies the fully-qualified hostname of the NFS client machine on which +you are working. +
-id +
Specifies a local UID number on the NFS client machine with which to +associate the tokens, if different from your local UID on the translator +machine. If this argument is omitted, the tokens are associated with an +NFS UID that matches your local UID on the translator machine. In both +cases, the NFS client software marks your AFS access requests with the NFS UID +when it forwards them to the Cache Manager on the translator machine. +
-sysname +
Specifies the value that the local machine's remote executor daemon +substitutes for the @sys variable in pathnames when executing AFS +commands issued on the NFS client machine (which must be a supported system +type). +
+
The following error message indicates that the translator machine's +administrator has enabled UID checking and you have provided a value that +differs from your local UID on the translator machine. +
```
   
+   knfs: Translator in 'passwd sync' mode; remote uid must be the same as local uid
+
```
+
Close the connection to the translator machine (if desired) and work on +the NFS client machine. +

+ +

To display tokens using the knfs command

Log on to the relevant translator machine, either on the console or +remotely by using a program such as telnet. +
Issue the knfs command with the -tokens flag to +display the tokens associated with either the NFS UID that matches your local +UID on the translator machine or the NFS UID specified by the -id +argument. +
```
   % knfs -host <host name>  [-id <user ID (decimal)>] -tokens
+
```
+
where +
+
-host +
Specifies the fully-qualified hostname of the NFS client machine on which +you are working. +
-id +
Specifies the local UID on the NFS client machine for which to display +tokens, if different from your local UID on the translator machine. If +this argument is omitted, the tokens are for the NFS UID that matches your +local UID on the translator machine. +
-tokens +
Displays the tokens. +
+
Close the connection to the translator machine if desired. +

+ +

To discard tokens using the knfs command

If you closed your connection to the translator machine after issuing the +knfs command, reopen it. +
Issue the knfs command with the -unlog flag. +
```
   % knfs -host  <host name>  [-id <user ID (decimal)>]  -unlog
+
```
+
where +
+
-host +
Specifies the fully-qualified hostname of the NFS client machine you are +working on. +
-id +
Specifies the local UID number on the NFS client machine for which to +discard the associated tokens, if different from your local UID on the +translator machine. If this argument is omitted, the tokens associated +with an NFS UID that matches your local UID on the translator machine are +discarded. +
-unlog +
Discards the tokens. +
+
If desired, close the connection to the translator machine. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd023.htm b/doc/html/AdminGuide/auagd023.htm new file mode 100644 index 0000000..6714535 --- /dev/null +++ b/doc/html/AdminGuide/auagd023.htm @@ -0,0 +1,369 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Appendix B. Using AFS Commands

This section describes the components of AFS commands and +how to make entering commands more efficient by using shortened forms. +It has the following sections: +

AFS Command Syntax +

Rules for Entering AFS Commands +

Rules for Using Abbreviations and Aliases +

Displaying Online Help for AFS Commands +

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
+   
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd024.htm b/doc/html/AdminGuide/auagd024.htm new file mode 100644 index 0000000..bd4df8c --- /dev/null +++ b/doc/html/AdminGuide/auagd024.htm @@ -0,0 +1,1552 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Appendix C. The afsmonitor Program Statistics

This Appendix lists the statistics you can gather with the +afsmonitor program, grouping them by category and section, and +briefly describing each field, group, and section. For instructions on +using the afsmonitor program, see Monitoring and Auditing AFS Performance + +

The Cache Manager Statistics

+ +

Cache Manager statistics fields are classified into the following sections +and groups: +

PerfStats_section - Performance Statistics Section. +
- PerfStats_group - Performance Statistics Group. +
- misc_group - Miscellaneous Group. +
+
Server_UpDown_section - Server Up/Down Statistics Section. +
- FS_upDown_SC_group - File Server Up/Down Statistics in Same Cell +Group. +
- FS_upDown_OC_group - File Server Up/Down Statistics in Other Cells +Group. +
- VL_upDown_SC_group - VL Server Up/Down Statistics in Same Cell +Group. +
- VL_upDown_OC_group - VL Server Up/Down Statistics in Other Cells +Group. +
+
RPCop_section - RPC Operation Measurements Section. +
- FS_RPCopTimes_group - File Server RPC Operation Timings +Group. +
- FS_RPCopErrors_group - File Server RPC Operation Errors +Group. +
- FS_RPCopBytes_group - File Server RPC Transfer Timings Group. +
- CM_RPCopTimes_group - Cache Manager RPC Operation Timings +Group. +
+
Auth_Access_section - Authentication and Replicated File Access +Section. +
- Auth_Stats_group - Authentication Information for Cache Manager +Group. +
- Access_Stats_group - Unreplicated File Access Group. +
+

All Cache Manager variables categorized under these sections and groups +names are listed below. +

Performance Statistics Section (PerfStats_section)

Performance Statistics Group (PerfStats_group) +

dlocalAccesses: Number of data accesses to files within local +cell. +
vlocalAccesses: Number of stat accesses to files within local +cell. +
dremoteAccesses: Number of data accesses to files outside of local +cell. +
vremoteAccesses: Number of stat accesses to files outside of local +cell. +
cacheNumEntries: Number of cache entries. +
cacheBlocksTotal: Number of (1K) blocks configured for cache. +
cacheBlocksInUse: Number of cache blocks actively in use. +
cacheBlocksOrig: Number of cache blocks at bootup. +
cacheMaxDirtyChunks: Maximum number of dirty cache chunks +tolerated. +
cacheCurrDirtyChunks: Current number of dirty cache chunks. +
dcacheHits: Number of data files found in local cache. +
vcacheHits: Number of stat entries found in local cache. +
dcacheMisses: Number of data files not found in local +cache. +
vcacheMisses: Number of stat entries not found in local +cache. +
cacheFlushes: Number of files flushed from cache. +
cacheFilesReused: Number of cache files reused. +
ProtServerAddr: Address of Protection Server used. +
vcacheXAllocs: Additionally allocated vcaches. +
bufAlloced: Number of buffers allocated by AFS. +
bufHits: Number of pages found on buffer cache. +
bufMisses: Number of pages not found on buffer +cache. +
bufFlushDirty: Number of cached dirty buffers flushed because all +were busy. +
LargeBlocksActive: Number of currently used large free pool +entries. +
LargeBlocksAlloced: Number of allocated large free pool +entries. +
SmallBlocksActive: Number of currently used small free pool +entries. +
SmallBlocksAlloced: Number of allocated used small free pool +entries. +
OutStandingMemUsage: Amount of allocated memory. +
OutStandingAllocs: Outstanding osi_allocs (no osi_frees yet). +
CallBackAlloced: Number of callback structures allocated. +
CallBackFlushes: Number of callback flush operations +performed. +
srvRecords: Number of servers currently on record. +
srvRecordsHWM: Server record high water mark. +
srvNumBuckets: Number of server hash chain buckets. +
srvMaxChainLength: Maximum server hash chain length. +
srvMaxChainLengthHWM: Server hash chain high water mark. +
sysName_ID: Sysname ID for host hardware. +

Miscellaneous Group (misc_group) +

numPerfCalls: Number of performance calls received. +
epoch: Cache Manager epoch time. +
numCellsVisible: Number of cells we know about. +
numCellsContacted: Number of cells contacted. +

Server Up/Down Statistics Section (Server_UpDown_section)

File Server Up/Down Statistics in Same Cell Group (FS_upDown_SC_group) +

Note: The records referred to in this section +are the internal records kept by the afsmonitor program to track +the processes from which data is being gathered. +

fs_sc_numTtlRecords: Number of fileserver records, active or +inactive. +
fs_sc_numUpRecords: Number of (active) fileserver records currently +marked up. +
fs_sc_numDownRecords: Number of (active) fileserver records +currently marked down. +
fs_sc_sumOfRecordAges: Sum of fileserver record lifetimes. +
fs_sc_ageOfYoungestRecord: Age of youngest fileserver record. +
fs_sc_ageOfOldestRecord: Age of oldest fileserver record. +
fs_sc_numDowntimeIncidents: Number of (completed) downtime +incidents. +
fs_sc_numRecordsNeverDown: Number of fileserver records never marked +down. +
fs_sc_maxDowntimesInARecord: Maximum downtimes seen by any +fileserver record. +
fs_sc_sumOfDowntimes: Sum of all (completed) downtimes, in +seconds. +
fs_sc_shortestDowntime: Shortest downtime, in seconds. +
fs_sc_longestDowntime: Longest downtime, in seconds. +
fs_sc_down_0_10_min: Down time incidents: 0-10 minutes. +
fs_sc_down_10_30_min: Down time incidents: 10-30 +minutes. +
fs_sc_down_half_1_hr: Down time incidents: 30-60 +minutes. +
fs_sc_down_1_2_hr: Down time incidents: 1-2 hours. +
fs_sc_down_2_4_hr: Down time incidents: 2-4 hours. +
fs_sc_down_4_8_hr: Down time incidents: 4-8 hours. +
fs_sc_down_more_8_hr: Down time incidents: more than 8 +hours. +
fs_sc_downDst_0: Down time incidents: 0 times. +
fs_sc_downDst_1: Down time incidents: 1 time. +
fs_sc_downDst_2_5: Down time incidents: 2-5 times. +
fs_sc_downDst_6_10: Down time incidents: 6-10 times. +
fs_sc_downDst_10_50: Down time incidents: 10-50 times. +
fs_sc_downDst_more_50: Down time incidents: more than 50 +times. +

File Server Up/Down Statistics in Other Cells Group (FS_upDown_OC_group) +

fs_oc_numTtlRecords: Number of fileserver records, active or +inactive. +
fs_oc_numUpRecords: Number of (active) fileserver records currently +marked up. +
fs_oc_numDownRecords: Number of (active) fileserver records +currently marked down. +
fs_oc_sumOfRecordAges: Sum of server record lifetimes. +
fs_oc_ageOfYoungestRecord: Age of youngest fileserver record. +
fs_oc_ageOfOldestRecord: Age of oldest fileserver record. +
fs_oc_numDowntimeIncidents: Number of (completed) downtime +incidents. +
fs_oc_numRecordsNeverDown: Number of fileserver records never marked +down. +
fs_oc_maxDowntimesInARecord: Maximum downtimes seen by any +fileserver. +
fs_oc_sumOfDowntimes: Sum of all (completed) downtimes, in +seconds. +
fs_oc_shortestDowntime: Shortest downtime, in seconds. +
fs_oc_longestDowntime: Longest downtime, in seconds. +
fs_oc_down_0_10_min: Down time incidents: 0-10 minutes. +
fs_oc_down_10_30_min: Down time incidents: 10-30 +minutes. +
fs_oc_down_half_1_hr: Down time incidents: 30-60 +minutes. +
fs_oc_down_1_2_hr: Down time incidents: 1-2 hours. +
fs_oc_down_2_4_hr: Down time incidents: 2-4 hours. +
fs_oc_down_4_8_hr: Down time incidents: 4-8 hours. +
fs_oc_down_more_8_hr: Down time incidents: more than 8 +hours. +
fs_oc_downDst_0: Down time incidents: 0 times. +
fs_oc_downDst_1: Down time incidents: 1 time. +
fs_oc_downDst_2_5: Down time incidents: 2-5 times. +
fs_oc_downDst_6_10: Down time incidents: 6-10 times. +
fs_oc_downDst_10_50: Down time incidents: 10-50 times. +
fs_oc_downDst_more_50: Down time incidents: more than 50 +times. +

VL Server Up/Down Statistics in Same Cell Group (VL_upDown_SC_group) +

vl_sc_numTtlRecords: Number of vlserver records, active or +inactive. +
vl_sc_numUpRecords: Number of (active) vlserver records currently +marked up. +
vl_sc_numDownRecords: Number of (active) vlserver records currently +marked down. +
vl_sc_sumOfRecordAges: Sum of vlserver record lifetimes. +
vl_sc_ageOfYoungestRecord: Age of youngest vlserver record. +
vl_sc_ageOfOldestRecord: Age of oldest vlserver record. +
vl_sc_numDowntimeIncidents: Number of (completed) downtime +incidents. +
vl_sc_numRecordsNeverDown: Number of vlserver records never marked +down. +
vl_sc_maxDowntimesInARecord: Maximum downtimes seen by any vlserver +record. +
vl_sc_sumOfDowntimes: Sum of all (completed) downtimes, in +seconds. +
vl_sc_shortestDowntime: Shortest downtime, in seconds. +
vl_sc_longestDowntime: Longest downtime, in seconds. +
vl_sc_down_0_10_min: Down time incidents: 0-10 minutes. +
vl_sc_down_10_30_min: Down time incidents: 10-30 +minutes. +
vl_sc_down_half_1_hr: Down time incidents: 30-60 +minutes. +
vl_sc_down_1_2_hr: Down time incidents: 1-2 hours. +
vl_sc_down_2_4_hr: Down time incidents: 2-4 hours. +
vl_sc_down_4_8_hr: Down time incidents: 4-8 hours. +
vl_sc_down_more_8_hr: Down time incidents: more than 8 +hours. +
vl_sc_downDst_0: Down time incidents: 0 times. +
vl_sc_downDst_1: Down time incidents: 1 time. +
vl_sc_downDst_2_5: Down time incidents: 2-5 times. +
vl_sc_downDst_6_10: Down time incidents: 6-10 times. +
vl_sc_downDst_10_50: Down time incidents: 10-50 times. +
vl_sc_downDst_more_50: Down time incidents: more than 50 +times. +

VL Server Up/Down Statistics in Other Cells Group (VL_upDown_DC_group) +

vl_oc_numTtlRecords: Number of vlserver records, active or +inactive. +
vl_oc_numUpRecords: Number of (active) vlserver records currently +marked up. +
vl_oc_numDownRecords: Number of (active) vlserver records currently +marked down. +
vl_oc_sumOfRecordAges: Sum of vlserver record lifetimes. +
vl_oc_ageOfYoungestRecord: Age of youngest vlserver record. +
vl_oc_ageOfOldestRecord: Age of oldest vlserver record. +
vl_oc_numDowntimeIncidents: Number of (completed) downtime +incidents. +
vl_oc_numRecordsNeverDown: Number of vlserver records never marked +down. +
vl_oc_maxDowntimesInARecord: Maximum downtimes seen by any vlserver +record. +
vl_oc_sumOfDowntimes: Sum of all (completed) downtimes, in +seconds. +
vl_oc_shortestDowntime: Shortest downtime, in seconds. +
vl_oc_longestDowntime: Longest downtime, in seconds. +
vl_oc_down_0_10_min: Down time incidents: 0-10 minutes. +
vl_oc_down_10_30_min: Down time incidents: 10-30 +minutes. +
vl_oc_down_half_1_hr: Down time incidents: 30-60 +minutes. +
vl_oc_down_1_2_hr: Down time incidents: 1-2 hours. +
vl_oc_down_2_4_hr: Down time incidents: 2-4 hours. +
vl_oc_down_4_8_hr: Down time incidents: 4-8 hours. +
vl_oc_down_more_8_hr: Down time incidents: more than 8 +hours. +
vl_oc_downDst_0: Down time incidents: 0 times. +
vl_oc_downDst_1: Down time incidents: 1 time. +
vl_oc_downDst_2_5: Down time incidents: 2-5 times. +
vl_oc_downDst_6_10: Down time incidents: 6-10 times. +
vl_oc_downDst_10_50: Down time incidents: 10-50 times. +
vl_oc_downDst_more_50: Down time incidents: more than 50 +times. +

RPC Operation Measurements Section (RPCop_section)

File Server RPC Operation Timings Group (FS_RPCopTimes_group) +

FetchData_ops: Number of FetchData operations executed. +
FetchData_ops_ok: Number of successful FetchData operations. +
FetchData_sum: Sum of timings for FetchData operations. +
FetchData_sqr: Sum of squares of sample timings for FetchData +operations. +
FetchData_min: Minimum execution time observed for FetchData +operations. +
FetchData_max: Maximum execution time observed for FetchData +operations. +
FetchACL_ops: Number of FetchACL operations executed. +
FetchACL_ops_ok: Number of successful FetchACL operations. +
FetchACL_sum: Sum of timings for FetchACL operations. +
FetchACL_sqr: Sum of squares of sample timings for FetchACL +operations. +
FetchACL_min: Minimum execution time observed for FetchACL +operations. +
FetchACL_max: Maximum execution time observed for FetchACL +operations. +
FetchStatus_ops: Number of FetchStatus operations executed. +
FetchStatus_ops_ok: Number of successful FetchStatus +operations. +
FetchStatus_sum: Sum of timings for FetchStatus operations. +
FetchStatus_sqr: Sum of squares of sample timings for FetchStatus +operations. +
FetchStatus_min: Minimum execution time observed for FetchStatus +operations. +
FetchStatus_max: Maximum execution time observed for FetchStatus +operations. +
StoreData_ops: Number of StoreData operations executed. +
StoreData_ops_ok: Number of successful StoreData operations. +
StoreData_sum: Sum of timings for StoreData operations. +
StoreData_sqr: Sum of squares of sample timings for StoreData +operations. +
StoreData_min: Minimum execution time observed for StoreData +operations. +
StoreData_max: Maximum execution time observed for StoreData +operations. +
StoreACL_ops: Number of StoreACL operations executed. +
StoreACL_ops_ok: Number of successful StoreACL operation. +
StoreACL_sum: Sum of timings for StoreACL operations. +
StoreACL_sqr: Sum of squares of sample timings for StoreACL +operations. +
StoreACL_min: Minimum execution time observed for StoreACL +operations. +
StoreACL_max: Maximum execution time observed for StoreACL +operations. +
StoreStatus_ops: Number of StoreStatus operations executed. +
StoreStatus_ops_ok: Number of successful StoreStatus +operations. +
StoreStatus_sum: Sum of timings for StoreStatus operations. +
StoreStatus_sqr: Sum of squares of sample timings for StoreStatus +operations. +
StoreStatus_min: Minimum execution time observed for StoreStatus +operations. +
StoreStatus_max: Maximum execution time observed for StoreStatus +operations. +
RemoveFile_ops: Number of RemoveFile operations executed. +
RemoveFile_ops_ok: Number of successful RemoveFile +operations. +
RemoveFile_sum: Sum of timings for RemoveFile operations. +
RemoveFile_sqr: Sum of squares of sample timings for RemoveFile +operations. +
RemoveFile_min: Minimum execution time observed for RemoveFile +operations. +
RemoveFile_max: Maximum execution time observed for RemoveFile +operations. +
CreateFile_ops: Number of CreateFile operations executed. +
CreateFile_ops_ok: Number of successful CreateFile +operations. +
CreateFile_sum: Sum of timings for CreateFile operations. +
CreateFile_sqr: Sum of squares of sample timings for CreateFile +operations. +
CreateFile_min: Minimum execution time observed for CreateFile +operations. +
CreateFile_max: Maximum execution time observed for CreateFile +operations. +
Rename_ops: Number of Rename operations executed. +
Rename_ops_ok: Number of successful Rename operations. +
Rename_sum: Sum of timings for Rename operations. +
Rename_sqr: Sum of squares of sample timings for Rename +operations. +
Rename_min: Minimum execution time observed for Rename +operations. +
Rename_max: Maximum execution time observed for Rename +operations. +
Symlink_ops: Number of Symlink operations executed. +
Symlink_ops_ok: Number of successful Symlink operations. +
Symlink_sum: Sum of timings for Symlink operations. +
Symlink_sqr: Sum of squares of sample timings for Symlink +operations. +
Symlink_min: Minimum execution time observed for Symlink +operations. +
Symlink_max: Maximum execution time observed for Symlink +operations. +
Link_ops: Number of Link operations executed. +
Link_ops_ok: Number of successful Link operations. +
Link_sum: Sum of timings for Link operations. +
Link_sqr: Sum of squares of sample timings for Link +operations. +
Link_min: Minimum execution time observed for Link +operations. +
Link_max: Maximum execution time observed for Link +operations. +
MakeDir_ops: Number of MakeDir operations executed. +
MakeDir_ops_ok: Number of successful MakeDir operations. +
MakeDir_sum: Sum of timings for MakeDir operations. +
MakeDir_sqr: Sum of squares of sample timings for MakeDir +operations. +
MakeDir_min: Minimum execution time observed for MakeDir +operations. +
MakeDir_max: Maximum execution time observed for MakeDir +operations. +
RemoveDir_ops: Number of RemoveDir operations executed. +
RemoveDir_ops_ok: Number of successful RemoveDir operations. +
RemoveDir_sum: Sum of timings for RemoveDir operations. +
RemoveDir_sqr: Sum of squares of sample timings for RemoveDir +operations. +
RemoveDir_min: Minimum execution time observed for RemoveDir +operations. +
RemoveDir_max: Maximum execution time observed for RemoveDir +operations. +
SetLock_ops: Number of SetLock operations executed. +
SetLock_ops_ok: Number of successful SetLock operations. +
SetLock_sum: Sum of timings for SetLock operations. +
SetLock_sqr: Sum of squares of sample timings for SetLock +operations. +
SetLock_min: Minimum execution time observed for SetLock +operations. +
SetLock_max: Maximum execution time observed for SetLock +operations. +
ExtendLock_ops: Number of ExtendLock operations executed. +
ExtendLock_ops_ok: Number of successful ExtendLock +operations. +
ExtendLock_sum: Sum of timings for ExtendLock operations. +
ExtendLock_sqr: Sum of squares of sample timings for ExtendLock +operations. +
ExtendLock_min: Minimum execution time observed for ExtendLock +operations. +
ExtendLock_max: Maximum execution time observed for ExtendLock +operations. +
ReleaseLock_ops: Number of ReleaseLock operations executed. +
ReleaseLock_ops_ok: Number of successful ReleaseLock +operations. +
ReleaseLock_sum: Sum of timings for ReleaseLock operations. +
ReleaseLock_sqr: Sum of squares of sample timings for StoreStatus +operations. +
ReleaseLock_min: Minimum execution time observed for ReleaseLock +operations. +
ReleaseLock_max: Maximum execution time observed for ReleaseLock +operations. +
GetStatistics_ops: Number of GetStatistics operations +executed. +
GetStatistics_ops_ok: Number of successful GetStatistics +operations. +
GetStatistics_sum: Sum of timings for GetStatistics +operations. +
GetStatistics_sqr: Sum of squares of sample timings for +GetStatistics operations. +
GetStatistics_min: Minimum execution time observed for GetStatistics +operations. +
GetStatistics_max: Maximum execution time observed for GetStatistics +operations. +
GiveUpCallbacks_ops: Number of GiveUpCallbacks operations +executed. +
GiveUpCallbacks_ops_ok: Number of successful GiveUpCallbacks +operations. +
GiveUpCallbacks_sum: Sum of timings for GiveUpCallbacks +operations. +
GiveUpCallbacks_sqr: Sum of squares of sample timings for +GiveUpCallbacks operations. +
GiveUpCallbacks_min: Minimum execution time observed for +GiveUpCallbacks operations. +
GiveUpCallbacks_max: Maximum execution time observed for +GiveUpCallbacks operations. +
GetVolumeInfo_ops: Number of GetVolumeInfo operations +executed. +
GetVolumeInfo_ops_ok: Number of successful GetVolumeInfo +operations. +
GetVolumeInfo_sum: Sum of timings for GetVolumeInfo +operations. +
GetVolumeInfo_sqr: Sum of squares of sample timings for +GetVolumeInfo operations. +
GetVolumeInfo_min: Minimum execution time observed for GetVolumeInfo +operations. +
GetVolumeInfo_max: Maximum execution time observed for GetVolumeInfo +operations. +
GetVolumeStatus_ops: Number of GetVolumeStatus operations +executed. +
GetVolumeStatus_ops_ok: Number of successful GetVolumeStatus +operations. +
GetVolumeStatus_sum: Sum of timings for GetVolumeStatus +operations. +
GetVolumeStatus_sqr: Sum of squares of sample timings for +GetVolumeStatus operations. +
GetVolumeStatus_min: Minimum execution time observed for +GetVolumeStatus operations. +
GetVolumeStatus_max: Maximum execution time observed for +GetVolumeStatus operations. +
SetVolumeStatus_ops: Number of SetVolumeStatus operations +executed. +
SetVolumeStatus_ops_ok: Number of successful SetVolumeStatus +operations. +
SetVolumeStatus_sum: Sum of timings for SetVolumeStatus +operations. +
SetVolumeStatus_sqr: Sum of squares of sample timings for +SetVolumeStatus operations. +
SetVolumeStatus_min: Minimum execution time observed for +SetVolumeStatus operations. +
SetVolumeStatus_max: Maximum execution time observed for +SetVolumeStatus operations. +
GetRootVolume_ops: Number of GetRootVolume operations +executed. +
GetRootVolume_ops_ok: Number of successful GetRootVolume +operations. +
GetRootVolume_sum: Sum of timings for GetRootVolume +operations. +
GetRootVolume_sqr: Sum of squares of sample timings for +GetRootVolume operations. +
GetRootVolume_min: Minimum execution time observed for GetRootVolume +operations. +
GetRootVolume_max: Maximum execution time observed for GetRootVolume +operations. +
CheckToken_ops: Number of CheckToken operations executed. +
CheckToken_ops_ok: Number of successful CheckToken +operations. +
CheckToken_sum: Sum of timings for CheckToken operations. +
CheckToken_sqr: Sum of squares of sample timings for CheckToken +operations. +
CheckToken_min: Minimum execution time observed for CheckToken +operations. +
CheckToken_max: Maximum execution time observed for CheckToken +operations. +
GetTime_ops: Number of GetTime operations executed. +
GetTime_ops_ok: Number of successful GetTime operations. +
GetTime_sum: Sum of timings for GetTime operations. +
GetTime_sqr: Sum of squares of sample timings for GetTime +operations. +
GetTime_min: Minimum execution time observed for GetTime +operations. +
GetTime_max: Maximum execution time observed for GetTime +operations. +
NGetVolumeInfo_ops: Number of NGetVolumeInfo operations +executed. +
NGetVolumeInfo_ops_ok: Number of successful NGetVolumeInfo +operations. +
NGetVolumeInfo_sum: Sum of timings for NGetVolumeInfo +operations. +
NGetVolumeInfo_sqr: Sum of squares of sample timings for +NGetVolumeInfo operations. +
NGetVolumeInfo_min: Minimum execution time observed for +NGetVolumeInfo operations. +
NGetVolumeInfo_max: Maximum execution time observed for +NGetVolumeInfo operations. +
BulkStatus_ops: Number of BulkStatus operations executed. +
BulkStatus_ops_ok: Number of successful BulkStatus +operations. +
BulkStatus_sum: Sum of timings for BulkStatus operations. +
BulkStatus_sqr: Sum of squares of sample timings for BulkStatus +operations. +
BulkStatus_min: Minimum execution time observed for BulkStatus +operations. +
BulkStatus_max: Maximum execution time observed for BulkStatus +operations. +
XStatsVersion_ops: Number of XStatsVersion operations +executed. +
XStatsVersion_ops_ok: Number of successful XStatsVersion +operations. +
XStatsVersion_sum: Sum of timings for XStatsVersion +operations. +
XStatsVersion_sqr: Sum of squares of sample timings for +XStatsVersion operations. +
XStatsVersion_min: Minimum execution time observed for XStatsVersion +operations. +
XStatsVersion_max: Maximum execution time observed for XStatsVersion +operations. +
GetXStats_ops: Number of GetXStats operations executed. +
GetXStats_ops_ok: Number of successful GetXStats operations. +
GetXStats_sum: Sum of timings for GetXStats operations. +
GetXstats_sqr: Sum of squares of sample timings for GetXStats +operations. +
GetXStats_min: Minimum execution time observed for GetXStats +operations. +
GetXStats_max: Maximum execution time observed for GetXStats +operations. +

File Server RPC Operation Errors Group (FS_RPCopErrors_group) +

FetchData_srv_err: Number of server-down errors during FetchData +operations. +
FetchData_net_err: Number of network errors during FetchData +operations. +
FetchData_prot_err_err: Number of protection violations during +FetchData operations. +
FetchData_vol_err: Number of volume related errors during FetchData +operations. +
FetchData_busy_err: Number of volume busy conditions during +FetchData operations. +
FetchData_other_err: Number of miscellaneous other errors during +FetchData operations. +
FetchACL_srv_err: Number of server-down errors during FetchACL +operations. +
FetchACL_net_err: Number of network errors during FetchACL +operations. +
FetchACL_prot_err: Number of protection violations during FetchACL +operations. +
FetchACL_vol_err: Number of volume related errors during FetchACL +operations. +
FetchACL_busy_err: Number of volume busy conditions encountered +during FetchACL operations. +
FetchACL_other_err: Number of miscellaneous other errors during +FetchACL operations. +
FetchStatus_srv_err: Number of server-down errors during FetchStatus +operations. +
FetchStatus_net_err: Number of network errors during FetchStatus +operations. +
FetchStatus_prot_err: Number of protection violations during +FetchStatus operations. +
FetchStatus_vol_err: Number of volume related errors during +FetchStatus operations. +
FetchStatus_busy_err: Number of volume busy conditions encountered +during FetchStatus operations. +
FetchStatus_other_err: Number of miscellaneous other errors during +FetchStatus operations. +
StoreData_srv_err: Number of server-down errors during StoreData +operations. +
StoreData_net_err: Number of network errors during StoreData +operations. +
StoreData_prot_err: Number of protection violations during StoreData +operations. +
StoreData_vol_err: Number of volume related errors during StoreData +operations. +
StoreData_busy_err: Number of volume busy conditions encountered +during StoreData operations. +
StoreData_other_err: Number of miscellaneous other errors during +StoreData operations. +
StoreACL_srv_err: Number of server-down errors during StoreACL +operations. +
StoreACL_net_err: Number of network errors during StoreACL +operations. +
StoreACL_prot_err: Number of protection violations during StoreACL +operations. +
StoreACL_vol_err: Number of volume related errors during StoreACL +operations. +
StoreACL_busy_err: Number of volume busy conditions encountered +during StoreACL operations. +
StoreACL_other_err: Number of miscellaneous other errors during +StoreACL operations. +
StoreStatus_srv_err: Number of server-down errors during StoreStatus +operations. +
StoreStatus_net_err: Number of network errors during StoreStatus +operations. +
StoreStatus_prot_err: Number of protection violations during +StoreStatus operations. +
StoreStatus_vol_err: Number of volume related errors during +StoreStatus operations. +
StoreStatus_busy_err: Number of volume busy conditions encountered +during StoreStatus operations. +
StoreStatus_other_err: Number of miscellaneous other errors during +StoreStatus operations. +
RemoveFile_srv_err: Number of server-down errors during RemoveFile +operations. +
RemoveFile_net_err: Number of network errors during RemoveFile +operations. +
RemoveFile_prot_err: Number of protection violations during +RemoveFile operations. +
RemoveFile_vol_err: Number of volume related errors during +RemoveFile operations. +
RemoveFile_busy_err: Number of volume busy conditions encountered +during RemoveFile operations. +
RemoveFile_other_err: Number of miscellaneous other errors during +RemoveFile operations. +
CreateFile_srv_err: Number of server-down errors during CreateFile +operations. +
CreateFile_net_err: Number of network errors during CreateFile +operations. +
CreateFile_prot_err: Number of protection violations during +CreateFile operations. +
CreateFile_vol_err: Number of volume related errors during +CreateFile operations. +
CreateFile_busy_err: Number of volume busy conditions encountered +during CreateFile operations. +
CreateFile_other_err: Number of miscellaneous other errors during +CreateFile operations. +
Rename_srv_err: Number of server-down errors during Rename +operations. +
Rename_net_err: Number of network errors during Rename +operations. +
Rename_prot_err: Number of protection violations during Rename +operations. +
Rename_vol_err: Number of volume related errors during Rename +operations. +
Rename_busy_err: Number of volume busy conditions encountered during +Rename operations. +
Rename_other_err: Number of miscellaneous other errors during Rename +operations. +
Symlink_srv_err: Number of server-down errors during Symlink +operations. +
Symlink_net_err: Number of network errors during Symlink +operations. +
Symlink_prot_err: Number of protection violations during Symlink +operations. +
Symlink_vol_err: Number of volume related errors during Symlink +operations. +
Symlink_busy_err: Number of volume busy conditions encountered +during Symlink operations. +
Symlink_other_err: Number of miscellaneous other errors during +Symlink operations. +
Link_srv_err: Number of server-down errors during Link +operations. +
Link_net_err: Number of network errors during Link +operations. +
Link_prot_err: Number of protection violations during Link +operations. +
Link_vol_err: Number of volume related errors during Link +operations. +
Link_busy_err: Number of volume busy conditions encountered during +Link operations. +
Link_other_err: Number of miscellaneous other errors during Link +operations. +
MakeDir_srv_err: Number of server-down errors during MakeDir +operations. +
MakeDir_net_err: Number of network errors during MakeDir +operations. +
MakeDir_prot_err: Number of protection violations during MakeDir +operations. +
MakeDir_vol_err: Number of volume related errors during MakeDir +operations. +
MakeDir_busy_err: Number of volume busy conditions encountered +during MakeDir operations. +
MakeDir_other_err: Number of miscellaneous other errors during +MakeDir operations. +
RemoveDir_srv_err: Number of server-down errors during RemoveDir +operations. +
RemoveDir_net_err: Number of network errors during RemoveDir +operations. +
RemoveDir_prot_err: Number of protection violations during RemoveDir +operations. +
RemoveDir_vol_err: Number of volume related errors during RemoveDir +operations. +
RemoveDir_busy_err: Number of volume busy conditions encountered +during RemoveDir operations. +
RemoveDir_other_err: Number of miscellaneous other errors during +RemoveDir operations. +
SetLock_srv_err: Number of server-down errors during SetLock +operations. +
SetLock_net_err: Number of network errors during SetLock +operations. +
SetLock_prot_err: Number of protection violations during SetLock +operations. +
SetLock_vol_err: Number of volume related errors during SetLock +operations. +
SetLock_busy_err: Number of volume busy conditions encountered +during SetLock operations. +
SetLock_other_err: Number of miscellaneous other errors during +SetLock operations. +
ExtendLock_srv_err: Number of server-down errors during ExtendLock +operations. +
ExtendLock_net_err: Number of network errors during ExtendLock +operations. +
ExtendLock_prot_err: Number of protection violations during +ExtendLock operations. +
ExtendLock_vol_err: Number of volume related errors during +ExtendLock operations. +
ExtendLock_busy_err: Number of volume busy conditions encountered +during ExtendLock operations. +
ExtendLock_other_err: Number of miscellaneous other errors during +ExtendLock operations. +
ReleaseLock_srv_err: Number of server-down errors during ReleaseLock +operations. +
ReleaseLock_net_err: Number of network errors during ReleaseLock +operations. +
ReleaseLock_prot_err: Number of protection violations during +ReleaseLock operations. +
ReleaseLock_vol_err: Number of volume related errors during +ReleaseLock operations. +
ReleaseLock_busy_err: Number of volume busy conditions encountered +during ReleaseLock operations. +
ReleaseLock_other_err: Number of miscellaneous other errors during +ReleaseLock operations. +
GetStatistics_srv_err: Number of server-down errors during +GetStatistics operations. +
GetStatistics_net_err: Number of network errors during GetStatistics +operations. +
GetStatistics_prot_err: Number of protection violations during +GetStatistics operations. +
GetStatistics_vol_err: Number of volume related errors during +GetStatistics operations. +
GetStatistics_busy_err: Number of volume busy conditions encountered +during GetStatistics operations. +
GetStatistics_other_err: Number of miscellaneous other errors during +GetStatistics operations. +
GiveUpCallbacks_srv_err: Number of server-down errors during +GiveUpCallbacks operations. +
GiveUpCallbacks_net_err: Number of network errors during +GiveUpCallbacks operations. +
GiveUpCallbacks_prot_err: Number of protection violations during +GiveUpCallbacks operations. +
GiveUpCallbacks_vol_err: Number of volume related errors during +GiveUpCallbacks operations. +
GiveUpCallbacks_busy_err: Number of volume busy conditions +encountered during GiveUpCallbacks operations. +
GiveUpCallbacks_other_err: Number of miscellaneous other errors +during GiveUpCallbacks operations. +
GetVolumeInfo_srv_err: Number of server-down errors during +GetVolumeInfo operations. +
GetVolumeInfo_net_err: Number of network errors during GetVolumeInfo +operations. +
GetVolumeInfo_prot_err: Number of protection violations during +GetVolumeInfo operations. +
GetVolumeInfo_vol_err: Number of volume related errors during +GetVolumeInfo operations. +
GetVolumeInfo_busy_err: Number of volume busy conditions encountered +during GetVolumeInfo operations. +
GetVolumeInfo_other_err: Number of miscellaneous other errors during +GetVolumeInfo operations. +
GetVolumeStatus_srv_err: Number of server-down errors during +GetVolumeStatus operations. +
GetVolumeStatus_net_err: Number of network errors during +GetVolumeStatus operations. +
GetVolumeStatus_prot_err: Number of protection violations during +GetVolumeStatus operations. +
GetVolumeStatus_vol_err: Number of volume related errors during +GetVolumeStatus operations. +
GetVolumeStatus_busy_err: Number of volume busy conditions +encountered during GetVolumeStatus operations. +
GetVolumeStatus_other_err: Number of miscellaneous other errors +during GetVolumeStatus operations. +
SetVolumeStatus_srv_err : Number of server-down errors during +SetVolumeStatus operations. +
SetVolumeStatus_net_err: Number of network errors during +SetVolumeStatus operations. +
SetVolumeStatus_prot_err: Number of protection violations during +SetVolumeStatus operations. +
SetVolumeStatus_vol_err: Number of volume related errors during +SetVolumeStatus operations. +
SetVolumeStatus_busy_err: Number of volume busy conditions +encountered during SetVolumeStatus operations. +
SetVolumeStatus_other_err: Number of miscellaneous other errors +during SetVolumeStatus operations. +
GetRootVolume_srv_err: Number of server-down errors during +GetRootVolume operations. +
GetRootVolume_net_err: Number of network errors during GetRootVolume +operations. +
GetRootVolume_prot_err: Number of protection violations during +GetRootVolume operations. +
GetRootVolume_vol_err: Number of volume related errors during +GetRootVolume operations. +
GetRootVolume_busy_err: Number of volume busy conditions encountered +during GetRootVolume operations. +
GetRootVolume_other_err: Number of miscellaneous other errors during +GetRootVolume operations. +
CheckToken_srv_err: Number of server-down errors during CheckToken +operations. +
CheckToken_net_err: Number of network errors during CheckToken +operations. +
CheckToken_prot_err: Number of protection violations during +CheckToken operations. +
CheckToken_vol_err: Number of volume related errors during +CheckToken operations. +
CheckToken_busy_err: Number of volume busy conditions encountered +during CheckToken operations. +
CheckToken_other_err: Number of miscellaneous other errors during +CheckToken operations. +
GetTime_srv_err: Number of server-down errors during GetTime +operations. +
GetTime_net_err: Number of network errors during GetTime +operations. +
GetTime_prot_err: Number of protection violations during GetTime +operations. +
GetTime_vol_err: Number of volume related errors during GetTime +operations. +
GetTime_busy_err: Number of volume busy conditions encountered +during GetTime operations. +
GetTime_other_err: Number of miscellaneous other errors during +GetTime operations. +
NGetVolumeInfo_srv_err: Number of server-down errors during +NGetVolumeInfo operations. +
NGetVolumeInfo_net_err: Number of network errors during +NGetVolumeInfo operations. +
NGetVolumeInfo_prot_err: Number of protection violations during +NGetVolumeInfo operations. +
NGetVolumeInfo_vol_err: Number of volume related errors during +NGetVolumeInfo operations. +
NGetVolumeInfo_busy_err: Number of volume busy conditions +encountered during NGetVolumeInfo operations. +
NGetVolumeInfo_other_err: Number of miscellaneous other errors +during NGetVolumeInfo operations. +
BulkStatus_srv_err: Number of server-down errors during BulkStatus +operations. +
BulkStatus_net_err: Number of network errors during BulkStatus +operations. +
BulkStatus_prot_err: Number of protection violations during +BulkStatus operations. +
BulkStatus_vol_err: Number of volume related errors during +BulkStatus operations. +
BulkStatus_busy_err: Number of volume busy conditions encountered +during BulkStatus operations. +
BulkStatus_other_err: Number of miscellaneous other errors during +BulkStatus operations. +
XStatsVersion_srv_err: Number of server-down errors during +XStatsVersion operations. +
XStatsVersion_net_err: Number of network errors during XStatsVersion +operations. +
XStatsVersion_prot_err: Number of protection violations during +XStatsVersion operations. +
XStatsVersion_vol_err: Number of volume related errors during +XStatsVersion operations. +
XStatsVersion_busy_err: Number of volume busy conditions encountered +during XStatsVersion operations. +
XStatsVersion_other_err: Number of miscellaneous other errors during +XStatsVersion operations. +
GetXStats_srv_err: Number of server-down errors during GetXStats +operations. +
GetXStats_net_err: Number of network errors during GetXStats +operations. +
GetXStats_prot_err: Number of protection violations during GetXStats +operations. +
GetXStats_vol_err: Number of volume related errors during GetXStats +operations. +
GetXStats_busy_err: Number of volume busy conditions encountered +during GetXStats operations. +
GetXStats_other_err: Number of miscellaneous other errors during +GetXStats operations. +

File Server RPC Transfer Timings Group (FS_RPCopBytes_group) +

FetchData_xfers: Number of FetchData operations. +
FetchData_xfers_ok: Number of successful FetchData +operations. +
FetchData_xfers_sum: Sum of timing values for FetchData +operations. +
FetchData_xfers_sqr: Sum of squares of sample timings for FetchData +operations. +
FetchData_xfers_min: Minimum transfer time observed for FetchData +operations. +
FetchData_xfers_max: Maximum transfer time observed for FetchData +operations. +
FetchData_xfers_bytes_sum: Sum of bytes transferred for FetchData +operations. +
FetchData_xfers_bytes_min: Minimum byte transfer observed for +FetchData operations. +
FetchData_xfers_bytes_max: Maximum byte transfer observed for +FetchData operations. +
FetchData_xfers_bucket0: Tally in bucket0 for FetchData +operations. +
FetchData_xfers_bucket1: Tally in bucket1 for FetchData +operations. +
FetchData_xfers_bucket2: Tally in bucket2 for FetchData +operations. +
FetchData_xfers_bucket3: Tally in bucket3 for FetchData +operations. +
FetchData_xfers_bucket4: Tally in bucket4 for FetchData +operations. +
FetchData_xfers_bucket5: Tally in bucket5 for FetchData +operations. +
FetchData_xfers_bucket6: Tally in bucket6 for FetchData +operations. +
FetchData_xfers_bucket7: Tally in bucket7 for FetchData +operations. +
FetchData_xfers_bucket8: Tally in bucket8 for FetchData +operations. +
StoreData_xfers: Number of StoreData operations. +
StoreData_xfers_ok: Number of successful StoreData +operations. +
StoreData_xfers_sum: Sum of timing values for StoreData +operations. +
StoreData_xfers_sqr: Sum of squares of sample timings for StoreData +operations. +
StoreData_xfers_min: Minimum transfer time observed for StoreData +operations. +
StoreData_xfers_max: Maximum transfer time observed for StoreData +operations. +
StoreData_xfers_bytes_sum: Sum of bytes transferred for StoreData +operations. +
StoreData_xfers_bytes_min: Minimum byte transfer observed for +StoreData operations. +
StoreData_xfers_bytes_max: Maximum byte transfer observed for +StoreData operations. +
StoreData_xfers_bucket0: Tally in bucket0 for StoreData +operations. +
StoreData_xfers_bucket1: Tally in bucket1 for StoreData +operations. +
StoreData_xfers_bucket2: Tally in bucket2 for StoreData +operations. +
StoreData_xfers_bucket3: Tally in bucket3 for StoreData +operations. +
StoreData_xfers_bucket4: Tally in bucket4 for StoreData +operations. +
StoreData_xfers_bucket5: Tally in bucket5 for StoreData +operations. +
StoreData_xfers_bucket6: Tally in bucket6 for StoreData +operations. +
StoreData_xfers_bucket7: Tally in bucket7 for StoreData +operations. +
StoreData_xfers_bucket8: Tally in bucket8 for StoreData +operations. +

Cache Manager RPC Operation Timings Group (CM_RPCopTimes_group) +

CallBack_ops: Number of CallBack operations executed. +
CallBack_ops_ok: Number of successful CallBack operations. +
CallBack_ops_sum: Sum of timings for CallBack operations. +
CallBack_ops_min: Minimum execution time observed for CallBack +operations. +
CallBack_ops_max: Maximum execution time observed for CallBack +operations. +
InitCallBackState_ops: Number of InitCallBackState operations +executed. +
InitCallBackState_ops_ok: Number of successful InitCallBackState +operations. +
InitCallBackState_ops_sum: Sum of timings for InitCallBackState +operations. +
InitCallBackState_ops_min: Minimum execution time observed for +InitCallBackState operations. +
InitCallBackState_ops_max: Maximum execution time observed for +InitCallBackState operations. +
Probe_ops: Number of Probe operations executed. +
Probe_ops_ok: Number of successful Probe operations. +
Probe_ops_sum: Sum of timings for Probe operations. +
Probe_ops_min: Minimum execution time observed for Probe +operations. +
Probe_ops_max: Maximum execution time observed for Probe +operations. +
GetLock_ops: Number of GetLock operations executed. +
GetLock_ops_ok: Number of successful GetLock operations. +
GetLock_ops_sum: Sum of timings for GetLock operations. +
GetLock_ops_min: Minimum execution time observed for GetLock +operations. +
GetLock_ops_max: Maximum execution time observed for GetLock +operations. +
GetCE_ops: Number of GetCE operations executed. +
GetCE_ops_ok: Number of successful GetCE operations. +
GetCE_ops_sum: Sum of timings for GetCE operations. +
GetCE_ops_min: Minimum execution time observed for GetCE +operations. +
GetCE_ops_max: Maximum execution time observed for GetCE +operations. +
XStatsVersion_CM_ops: Number of XStatsVersion operations +executed. +
XStatsVersion_CM_ops_ok: Number of successful XStatsVersion +operations. +
XStatsVersion_CM_ops_sum: Sum of timings for XStatsVersion +operations. +
XStatsVersion_CM_ops_min: Minimum execution time observed for +XStatsVersion operations. +
XStatsVersion_CM_ops_max: Maximum execution time observed for +XStatsVersion operations. +
GetXStats_CM_ops: Number of GetXStats operations executed. +
GetXStats_CM_ops_ok: Number of successful GetXStats +operations. +
GetXStats_CM_ops_sum: Sum of timings for GetXStats +operations. +
GetXStats_CM_ops_min: Minimum execution time observed for GetXStats +operations. +
GetXStats_CM_ops_max: Maximum execution time observed for GetXStats +operations. +

Authentication and Replicated File Access Section (Auth_Access_section)

Authentication Information for Cache Manager Group (Auth_Stats_group) +

curr_PAGs: Current number of PAGs. +
curr_Records: Current number of records in table. +
curr_AuthRecords: Current number of of authenticated records (with +valid ticket). +
curr_UnauthRecords: Current number of of unauthenticated records +(without any ticket at all). +
curr_MaxRecordsInPAG: Maximum records for a single PAG. +
curr_LongestChain: Length of longest current hash chain. +
PAGCreations: Number of PAG creations. +
TicketUpdates: Number of ticket additions/refreshes. +
HWM_PAGS: High water mark - number of PAGs. +
HWM_Records: High water mark - number of records. +
HWM_MaxRecordsInPAG: High water mark - maximum records for a +single PAG. +
HWM_LongestChain: High water mark - longest hash chain. +

Unreplicated File Access Group (Access_Stats_group) +

unreplicatedRefs: Number of references to unreplicated data. +
replicatedRefs: Number of references to replicated data. +
numReplicasAccessed: Number of replicas accessed. +
maxReplicasPerRef: Maximum number of replicas accessed per +reference. +
refFirstReplicaOK: Number of references satisfied by 1st +replica. +

The File Server Statistics

+ +

File Server statistics are classified into the following sections and +groups: +

PerfStats_section: Performance Statistics Section. +
- VnodeCache_group: Vnode Cache Group. +
- Directory_group: Directory Package Group. +
- Rx_group: Rx Group. +
- HostModule_group: Host Module Fields Group. +
- misc_group: Miscellaneous Variables Group. +
+
RPCop_section: RPC Operations Section. +
- RPCopTimes_group: Individual RPC Operation Timings. +
- RPCopBytes_group: Byte Information for Certain RPC +Operations. +
+

All File Server variables categorized under the above sections and groups +names are listed below. +

Performance Statistics Section (PerfStats_section)

Vnode Cache Group (VnodeCache_group) +

vcache_L_Entries: Number of entries in LARGE vnode cache. +
vcache_L_Allocs: Number of allocs (large). +
vcache_L_Gets: Number of gets (large). +
vcache_L_Reads: Number of reads (large). +
vcache_L_Writes: Number of writes (large). +
vcache_S_Entries: Number of entries in SMALL vnode cache. +
vcache_S_Allocs: Number of allocs (small). +
vcache_S_Gets: Number of gets (small). +
vcache_S_Reads: Number of reads (small). +
vcache_S_Writes: Number of writes (small). +
vcache_H_Entries: Number of entries in HEADER vnode cache. +
vcache_H_Gets: Number of gets (header) +
vcache_H_Replacements: Number of replacements (header) +

Directory Package Group (Directory_group) +

dir_Buffers: Number of buffers in use. +
dir_Calls: Number of read calls made. +
dir_IOs: I/O operations performed. +

Rx Group (Rx_group) +

rx_packetRequests: Packet allocation requests. +
rx_noPackets_RcvClass: Failed packet requests (receive +class). +
rx_noPackets_SendClass: Failed packet requests (send class). +
rx_noPackets_SpecialClass: Failed packet requests (special +class). +
rx_socketGreedy: Did SO_GREEDY succeed? +
rx_bogusPacketOnRead: Short packets received. +
rx_bogusHost: Host address from bogus packets. +
rx_noPacketOnRead: Read packets with no packet there. +
rx_noPacketBuffersOnRead: Packets dropped due to buffer +shortage. +
rx_selects: Selects waiting on packet or timeout. +
rx_sendSelects: Selects forced upon sends. +
rx_packetsRead_RcvClass: Packets read (receive class). +
rx_packetsRead_SendClass: Packets read (send class). +
rx_packetsRead_SpecialClass: Packets read (special class). +
rx_dataPacketsRead: Unique data packets read off wire. +
rx_ackPacketsRead: ACK packets read. +
rx_dupPacketsRead: Duplicate data packets read. +
rx_spuriousPacketsRead: Inappropriate packets read. +
rx_packetsSent_RcvClass: Packets sent (receive class). +
rx_packetsSent_SendClass: Packets sent (send class). +
rx_packetsSent_SpecialClass: Packets sent (special class). +
rx_ackPacketsSent: ACK packets sent. +
rx_pingPacketsSent: Ping packets sent. +
rx_abortPacketsSent: Abort packets sent. +
rx_busyPacketsSent: Busy packets sent. +
rx_dataPacketsSent: Unique data packets sent. +
rx_dataPacketsReSent: Retransmissions sent. +
rx_dataPacketsPushed: Retransmissions pushed by NACK. +
rx_ignoreAckedPacket: Packets with ACKed flag on rxi_Start. +
rx_totalRtt_Sec and rx_totalRtt_Usec: Total round trip time (in +seconds and milliseconds). +
rx_minRtt_Sec and rx_minRtt_Usec: Minimum round trip time (in +seconds and milliseconds). +
rx_maxRtt_Sec and rx_maxRtt_Usec: Maximum round trip time (in +seconds and milliseconds). +
rx_nRttSamples: Round trip samples. +
rx_nServerConns: Total server connections. +
rx_nClientConns: Total client connections. +
rx_nPeerStructs: Total peer structures. +
rx_nCallStructs: Total call structures. +
rx_nFreeCallStructs: Total free call structures. +

Host Module Fields Group (HostModule_group) +

host_NumHostEntries: Number of host entries. +
host_HostBlocks: Blocks in use for hosts. +
host_NonDeletedHosts: Non-deleted hosts. +
host_HostsInSameNetOrSubnet: Hosts in same subnet as server. +
host_HostsInDiffSubnet: Hosts in different subnet than +server. +
host_HostsInDiffNetwork: Hosts in different network than +server. +
host_NumClients: Number of client entries. +
host_ClientBlocks: Blocks in use for clients. +

Miscellaneous Variables Group (misc_group) +

numPerfCalls: Number of performance calls received. +

RPC Operations Section (RPCop_section)

Individual RPC Operation Timings Group (RPCopTimes_group) +

epoch: Time when data collection began. +
FetchData_ops: Number of FetchData operations executed. +
FetchData_ops_ok: Number of successful FetchData operations. +
FetchData_sum: Sum of timings for FetchData operations. +
FetchData_sqr: Sum of squares of sample timings for FetchData +operations. +
FetchData_min: Minimum execution time observed for FetchData +operations. +
FetchData_max: Maximum execution time observed for FetchData +operations. +
FetchACL_ops: Number of FetchACL operations executed. +
FetchACL_ops_ok: Number of successful FetchACL operations. +
FetchACL_sum: Sum of timings for FetchACL operations. +
FetchACL_sqr: Sum of squares of sample timings for FetchACL +operations. +
FetchACL_min: Minimum execution time observed for FetchACL +operations. +
FetchACL_max: Maximum execution time observed for FetchACL +operations. +
FetchStatus_ops: Number of FetchStatus operations executed. +
FetchStatus_ops_ok: Number of successful FetchStatus +operations. +
FetchStatus_sum: Sum of timings for FetchStatus operations. +
FetchStatus_sqr: Sum of squares of sample timings for FetchStatus +operations. +
FetchStatus_min: Minimum execution time observed for FetchStatus +operations. +
FetchStatus_max: Maximum execution time observed for FetchStatus +operations. +
StoreData_ops: Number of StoreData operations executed. +
StoreData_ops_ok: Number of successful StoreData operations. +
StoreData_sum: Sum of timings for StoreData operations. +
StoreData_sqr: Sum of squares of sample timings for StoreData +operations. +
StoreData_min: Minimum execution time observed for StoreData +operations. +
StoreData_max: Maximum execution time observed for StoreData +operations. +
StoreACL_ops: Number of StoreACL operations executed. +
StoreACL_ops_ok: Number of successful StoreACL operations. +
StoreACL_sum: Sum of timings for StoreACL operations. +
StoreACL_sqr: Sum of squares of sample timings for StoreACL +operations. +
StoreACL_min: Minimum execution time observed for StoreACL +operations. +
StoreACL_max: Maximum execution time observed for StoreACL +operations. +
StoreStatus_ops: Number of StoreStatus operations executed. +
StoreStatus_ops_ok: Number of successful StoreStatus +operations. +
StoreStatus_sum: Sum of timings for StoreStatus operations. +
StoreStatus_sqr: Sum of squares of sample timings for StoreStatus +operations. +
StoreStatus_min: Minimum execution time observed for StoreStatus +operations. +
StoreStatus_max: Maximum execution time observed for StoreStatus +operations. +
RemoveFile_ops: Number of RemoveFile operations executed. +
RemoveFile_ops_ok: Number of successful RemoveFile +operations. +
RemoveFile_sum: Sum of timings for RemoveFile operations. +
RemoveFile_sqr: Sum of squares of sample timings for RemoveFile +operations. +
RemoveFile_min: Minimum execution time observed for RemoveFile +operations. +
RemoveFile_max: Maximum execution time observed for RemoveFile +operations. +
CreateFile_ops: Number of CreateFile operations executed. +
CreateFile_ops_ok: Number of successful CreateFile +operations. +
CreateFile_sum: Sum of timings for CreateFile operations. +
CreateFile_sqr: Sum of squares of sample timings for CreateFile +operations. +
CreateFile_min: Minimum execution time observed for CreateFile +operations. +
CreateFile_max: Maximum execution time observed for CreateFile +operations. +
Rename_ops: Number of Rename operations executed. +
Rename_ops_ok: Number of successful Rename operations. +
Rename_sum: Sum of timings for Rename operations. +
Rename_sqr: Sum of squares of sample timings for Rename +operations. +
Rename_min: Minimum execution time observed for Rename +operations. +
Rename_max: Maximum execution time observed for Rename +operations. +
Symlink_ops: Number of Symlink operations executed. +
Symlink_ops_ok: Number of successful Symlink operations. +
Symlink_sum: Sum of timings for Symlink operations. +
Symlink_sqr: Sum of squares of sample timings for Symlink +operations. +
Symlink_min: Minimum execution time observed for Symlink +operations. +
Symlink_max: Maximum execution time observed for Symlink +operations. +
Link_ops: Number of Link operations executed. +
Link_ops_ok: Number of successful Link operations. +
Link_sum: Sum of timings for Link operations. +
Link_sqr: Sum of squares of sample timings for Link +operations. +
Link_min: Minimum execution time observed for Link +operations. +
Link_max: Maximum execution time observed for Link +operations. +
MakeDir_ops: Number of MakeDir operations executed. +
MakeDir_ops_ok: Number of successful MakeDir operations. +
MakeDir_sum: Sum of timings for MakeDir operations. +
MakeDir_sqr: Sum of squares of sample timings for MakeDir +operations. +
MakeDir_min: Minimum execution time observed for MakeDir +operations. +
MakeDir_max: Maximum execution time observed for MakeDir +operations. +
RemoveDir_ops: Number of RemoveDir operations executed. +
RemoveDir_ops_ok: Number of successful RemoveDir operations. +
RemoveDir_sum: Sum of timings for RemoveDir operations. +
RemoveDir_sqr: Sum of squares of sample timings for RemoveDir +operations. +
RemoveDir_min: Minimum execution time observed for RemoveDir +operations. +
RemoveDir_max: Maximum execution time observed for RemoveDir +operations. +
SetLock_ops: Number of SetLock operations executed. +
SetLock_ops_ok: Number of successful SetLock operations. +
SetLock_sum: Sum of timings for SetLock operations. +
SetLock_sqr: Sum of squares of sample timings for SetLock +operations. +
SetLock_min: Minimum execution time observed for SetLock +operations. +
SetLock_max: Maximum execution time observed for SetLock +operations. +
ExtendLock_ops: Number of ExtendLock operations executed. +
ExtendLock_ops_ok: Number of successful ExtendLock +operations. +
ExtendLock_sum: Sum of timings for ExtendLock operations. +
ExtendLock_sqr: Sum of squares of sample timings for ExtendLock +operations. +
ExtendLock_min: Minimum execution time observed for ExtendLock +operations. +
ExtendLock_max: Maximum execution time observed for ExtendLock +operations. +
ReleaseLock_ops: Number of ReleaseLock operations executed. +
ReleaseLock_ops_ok: Number of successful ReleaseLock +operations. +
ReleaseLock_sum: Sum of timings for ReleaseLock operations. +
ReleaseLock_sqr: Sum of squares of sample timings for ReleaseLock +operations. +
ReleaseLock_min: Minimum execution time observed for ReleaseLock +operations. +
ReleaseLock_max: Maximum execution time observed for ReleaseLock +operations. +
GetStatistics_ops: Number of GetStatistics operations +executed. +
GetStatistics_ops_ok: Number of successful GetStatistics +operations. +
GetStatistics_sum: Sum of timings for GetStatistics +operations. +
GetStatistics_sqr: Sum of squares of sample timings for +GetStatistics operations. +
GetStatistics_min: Minimum execution time observed for GetStatistics +operations. +
GetStatistics_max: Maximum execution time observed for GetStatistics +operations. +
GiveUpCallbacks_ops: Number of GiveUpCallbacks operations +executed. +
GiveUpCallbacks_ops_ok: Number of successful GiveUpCallbacks +operations. +
GiveUpCallbacks_sum: Sum of timings for GiveUpCallbacks +operations. +
GiveUpCallbacks_sqr: Sum of squares of sample timings for +GiveUpCallbacks operations. +
GiveUpCallbacks_min: Minimum execution time observed for +GiveUpCallbacks operations. +
GiveUpCallbacks_max: Maximum execution time observed for +GiveUpCallbacks operations. +
GetVolumeInfo_ops: Number of GetVolumeInfo operations +executed. +
GetVolumeInfo_ops_ok: Number of successful GetVolumeInfo +operations. +
GetVolumeInfo_sum: Sum of timings for GetVolumeInfo +operations. +
GetVolumeInfo_sqr: Sum of squares of sample timings for +GetVolumeInfo operations. +
GetVolumeInfo_min: Minimum execution time observed for GetVolumeInfo +operations. +
GetVolumeInfo_max: Maximum execution time observed for GetVolumeInfo +operations. +
GetVolumeStatus_ops: Number of GetVolumeStatus operations +executed. +
GetVolumeStatus_ops_ok: Number of successful GetVolumeStatus +operations. +
GetVolumeStatus_sum: Sum of timings for GetVolumeStatus +operations. +
GetVolumeStatus_sqr: Sum of squares of sample timings for +GetVolumeStatus operations. +
GetVolumeStatus_min: Minimum execution time observed for +GetVolumeStatus operations. +
GetVolumeStatus_max: Maximum execution time observed for +GetVolumeStatus operations. +
SetVolumeStatus_ops: Number of SetVolumeStatus operations +executed. +
SetVolumeStatus_ops_ok: Number of successful SetVolumeStatus +operations. +
SetVolumeStatus_sum: Sum of timings for SetVolumeStatus +operations. +
SetVolumeStatus_sqr: Sum of squares of sample timings for +SetVolumeStatus operations. +
SetVolumeStatus_min: Minimum execution time observed for +SetVolumeStatus operations. +
SetVolumeStatus_max: Maximum execution time observed for +SetVolumeStatus operations. +
GetRootVolume_ops: Number of GetRootVolume operations +executed. +
GetRootVolume_ops_ok: Number of successful GetRootVolume +operations. +
GetRootVolume_sum: Sum of timings for GetRootVolume +operations. +
GetRootVolume_sqr: Sum of squares of sample timings for +GetRootVolume operations. +
GetRootVolume_min: Minimum execution time observed for GetRootVolume +operations. +
GetRootVolume_max: Maximum execution time observed for GetRootVolume +operations. +
CheckToken_ops: Number of CheckToken operations executed. +
CheckToken_ops_ok: Number of successful CheckToken +operations. +
CheckToken_sum: Sum of timings for CheckToken operations. +
CheckToken_sqr: Sum of squares of sample timings for CheckToken +operations. +
CheckToken_min: Minimum execution time observed for CheckToken +operations. +
CheckToken_max: Maximum execution time observed for CheckToken +operations. +
GetTime_ops: Number of GetTime operations executed. +
GetTime_ops_ok: Number of successful GetTime operations. +
GetTime_sum: Sum of timings for GetTime operations. +
GetTime_sqr: Sum of squares of sample timings for GetTime +operations. +
GetTime_min: Minimum execution time observed for GetTime +operations. +
GetTime_max: Maximum execution time observed for GetTime +operations. +
NGetVolumeInfo_ops: Number of NGetVolumeInfo operations +executed. +
NGetVolumeInfo_ops_ok: Number of successful NGetVolumeInfo +operations. +
NGetVolumeInfo_sum: Sum of timings for NGetVolumeInfo +operations. +
NGetVolumeInfo_sqr: Sum of squares of sample timings for +NGetVolumeInfo operations. +
NGetVolumeInfo_min: Minimum execution time observed for +NGetVolumeInfo operations. +
NGetVolumeInfo_max: Maximum execution time observed for +NGetVolumeInfo operations. +
BulkStatus_ops: Number of BulkStatus operations executed. +
BulkStatus_ops_ok: Number of successful BulkStatus +operations. +
BulkStatus_sum: Sum of timings for BulkStatus operations. +
BulkStatus_sqr: Sum of squares of sample timings for BulkStatus +operations. +
BulkStatus_min: Minimum execution time observed for BulkStatus +operations. +
BulkStatus_max: Maximum execution time observed for BulkStatus +operations. +
XStatsVersion_ops: Number of XStatsVersion operations +executed. +
XStatsVersion_ops_ok: Number of successful XStatsVersion +operations. +
XStatsVersion_sum: Sum of timings for XStatsVersion +operations. +
XStatsVersion_sqr: Sum of squares of sample timings for +XStatsVersion operations. +
XStatsVersion_min: Minimum execution time observed for XStatsVersion +operations. +
XStatsVersion_max: Maximum execution time observed for XStatsVersion +operations. +
GetXStats_ops: Number of GetXStats operations executed. +
GetXStats_ops_ok: Number of successful GetXStats operations. +
GetXStats_sum: Sum of timings for GetXStats operations. +
GetXStats_sqr: Sum of squares of sample timings for GetXStats +operations. +
GetXStats_min: Minimum execution time observed for GetXStats +operations. +
GetXStats_max: Maximum execution time observed for GetXStats +operations. +

Byte Information for Certain RPC Operations Group (RPCopBytes_group) +

FetchData_xfers: Number of FetchData operations. +
FetchData_xfers_ok: Number of successful FetchData +operations. +
FetchData_xfers_sum: Sum of timing values for FetchData +operations. +
FetchData_xfers_sqr: Sum of squares of sample timings for FetchData +operations. +
FetchData_xfers_min: Minimum transfer time observed for FetchData +operations. +
FetchData_xfers_max: Maximum transfer time observed for FetchData +operations. +
FetchData_xfers_bytes_sum: Sum of bytes transferred for FetchData +operations. +
FetchData_xfers_bytes_min: Minimum byte transfer observed for +FetchData operations. +
FetchData_xfers_bytes_max: Maximum byte transfer observed for +FetchData operations. +
FetchData_xfers_bucket0: Tally in bucket0 for FetchData +operations. +
FetchData_xfers_bucket1: Tally in bucket1 for FetchData +operations. +
FetchData_xfers_bucket2: Tally in bucket2 for FetchData +operations. +
FetchData_xfers_bucket3: Tally in bucket3 for FetchData +operations. +
FetchData_xfers_bucket4: Tally in bucket4 for FetchData +operations. +
FetchData_xfers_bucket5: Tally in bucket5 for FetchData +operations. +
FetchData_xfers_bucket6: Tally in bucket6 for FetchData +operations. +
FetchData_xfers_bucket7: Tally in bucket7 for FetchData +operations. +
FetchData_xfers_bucket8: Tally in bucket8 for FetchData +operations. +
StoreData_xfers: Number of StoreData operations. +
StoreData_xfers_ok: Number of successful StoreData +operations. +
StoreData_xfers_sum: Sum of timing values for StoreData +operations. +
StoreData_xfers_sqr: Sum of squares of sample timings for StoreData +operations. +
StoreData_xfers_min: Minimum transfer time observed for StoreData +operations. +
StoreData_xfers_max: Maximum transfer time observed for StoreData +operations. +
StoreData_xfers_bytes_sum: Sum of bytes transferred for StoreData +operations. +
StoreData_xfers_bytes_min: Minimum byte transfer observed for +StoreData operations. +
StoreData_xfers_bytes_max: Maximum byte transfer observed for +StoreData operations. +
StoreData_xfers_bucket0: Tally in bucket0 for StoreData +operations. +
StoreData_xfers_bucket1: Tally in bucket1 for StoreData +operations. +
StoreData_xfers_bucket2: Tally in bucket2 for StoreData +operations. +
StoreData_xfers_bucket3: Tally in bucket3 for StoreData +operations. +
StoreData_xfers_bucket4: Tally in bucket4 for StoreData +operations. +
StoreData_xfers_bucket5: Tally in bucket5 for StoreData +operations. +
StoreData_xfers_bucket6: Tally in bucket6 for StoreData +operations. +
StoreData_xfers_bucket7: Tally in bucket7 for StoreData +operations. +
StoreData_xfers_bucket8: Tally in bucket8 for StoreData +operations. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd025.htm b/doc/html/AdminGuide/auagd025.htm new file mode 100644 index 0000000..7f46b64 --- /dev/null +++ b/doc/html/AdminGuide/auagd025.htm @@ -0,0 +1,1079 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Appendix D. AIX Audit Events

This Appendix provides a complete listing of the AFS events +that can be audited on AIX file server machines. See Chapter Monitoring and Auditing AFS Performance for instructions on auditing AFS events on AIX file server +machines. + +

Introduction

Below is a list of the AFS events contained in the file +/afs/usr/local/audit/events.sample. Each entry +contains information on the event class, the name of the event, the parameters +associated with the event, and a description of the event. +

Most events have an associated error code that shows the outcome of the +event (since each event is recorded after it occurs), an AFSName (the +authentication identify of the requesting process), and a host ID (from which +the request originated). Many events follow the RPC server entry calls +defined in the AFS Programmer's Reference Manual. +

Events are classed by functionality (this is AIX specific). Some +events possibly fall into one of more of the following classes which are +defined by the file /usr/afs/local/config.sample: +

A (afsauthent): Authentication and Identification Events +
S (afssecurity): Security Events +
P (afsprivilege): Privilege Required Events +
O (afsobjects): Object Creation and Deletion Events +
M (afsattributes): Attribute modification +
C (afsprocess): Process Control Events +

Audit-Specific Events

+
+ + + + + + +

Event +	Class +	Parameters +	Description +
AFS_Audit_WR +	None +	<string> +	The file "/usr/afs/Audit" has been written to (AIX specific +event). +
AFS_Aud_On +	S +	ECode +	Auditing is on for this server process (recorded on startup of a +server). +
AFS_Aud_Off +	S +	ECode +	Auditing is off for this server process (recorded on startup of a +server). +
AFS_Aud_Unauth +	S +	ECode Event +	Event triggered by an unauthorized user. +

Note:

The following audit-specific events indicate an error has occurred while +recording the event. Most events have an AFSName associated with them +and a host ID. If this information cannot be gathered out of the Rx +structure, one of these events is raised. +

+
+ + + + + + + + +

Event +	Class +	Parameters +	Description +
AFS_Aud_NoCall +	S +	ECode Event +	No rx call structure with this event. Cannot get security, AFS ID, +or origin of call. +
AFS_Aud_NoConn +	S +	ECode Event +	No connection info associated with rx call. Cannot get security, +AFS ID, or origin of call. +
AFS_Aud_UnknSec +	S +	ECode Event +	Security of call is unknown (must be authorized or unauthorized +caller). +
AFS_Aud_NoAFSId +	S +	ECode Event +	No AFS ID/name associated with a secure event. +
AFS_Aud_NoHost +	S +	ECode Event +	No information about origin (machine) of caller. +
AFS_Aud_EINVAL +	None +	Event +	Error in audit event parameter (can't record the event +parameter). +

Volume Server Events

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Event +	Class +	Parameters +	Description +
AFS_VS_Start +	P C +	ECode +	The volume server has started. +
AFS_VS_Finish +	C +	ECode +	The volume server has finished. Finish events are rare since the +server process is normally aborted. +
AFS_VS_Exit +	C +	ECode +	The volume server has exited. Exit events are rare since the +server process is normally aborted. +
AFS_VS_TransCr +	None +	ECode AFSName HostID Trans VolID +	AFSVolTransCreate - Create transaction for a [volume, partition] +
AFS_VS_EndTrn +	None +	ECode AFSName HostID Trans +	AFSVolEndTrans - End a transaction. +
AFS_VS_CrVol +	P O +	ECode AFSName HostID Trans VolID VolName Type ParentID +	AFSVolCreateVolume - Create a volume (volumeId volumeName) +
AFS_VS_DelVol +	P O +	ECode AFSName HostID Trans +	AFSVolDeleteVolume - Delete a volume. +
AFS_VS_NukVol +	P O +	ECode AFSName HostID VolID +	AFSVolNukeVolume - Obliterate a volume completely (volume ID). +
AFS_VS_Dump +	None +	ECode AFSName HostID Trans +	AFSVolDump - Dump the contents of a volume. +
AFS_VS_SigRst +	P M +	ECode AFSName HostID VolName +	AFSVolSignalRestore - Show intention to call AFSVolRestore. +
AFS_VS_Restore +	P O +	ECode AFSName HostID Trans +	AFSVolRestore - Recreate a volume from a dump. +
AFS_VS_Forward +	P O +	ECode AFSName HostID FromTrans Host DestTrans +	AFSVolForward - Dump a volume, then restore to a given server and +volume. +
AFS_VS_Clone +	P O +	ECode AFSName HostID Trans Purge NewName NewType NewVolID +	AFSVolClone - Clone (and optionally purge) a volume. +
AFS_VS_ReClone +	P O +	ECode AFSName HostID Trans CloneVolID +	AFSVolReClone - Reclone a volume. +
AFS_VS_SetForw +	P M +	ECode AFSName HostID Trans NewHost +	AFSVolSetForwarding - Set forwarding information for a moved +volume. +
AFS_VS_GetFlgs +	None +	ECode AFSName HostID Trans +	AFSVolGetFlags - Get volume flags for a transaction. +
AFS_VS_SetFlgs +	P M +	ECode AFSName HostID Trans Flags +	AFSVolSetFlags - Set volume flags for a transaction. +
AFS_VS_GetName +	None +	ECode AFSName HostID Trans +	AFSVolGetName - Get the volume name associated with a transaction. +
AFS_VS_GetStat +	None +	ECode AFSName HostID Trans +	AFSVolGetStatus - Get status of a transaction/volume. +
AFS_VS_SetIdTy +	P M +	ECode AFSName HostID Trans VolName Type ParentId CloneID BackupID +	AFSVolSetIdsTypes - Set header information for a volume. +
AFS_VS_SetDate +	P M +	ECode AFSName HostID Trans Date +	AFSVolSetDate - Set creation date in a volume. +
AFS_VS_ListPar +	None +	ECode AFSName HostID +	AFSVolListPartitions - Return a list of AFS partitions on a +server. +
AFS_VS_ParInf +	None +	ECode AFSName HostID PartName +	AFSVolPartitionInfo - Get partition information. +
AFS_VS_ListVol +	None +	ECode AFSName HostID +	AFSVolListVolumes - Return a list of volumes on a server. +
AFS_VS_XLstVol +	None +	ECode AFSName HostID +	AFSVolXListVolumes - Return a (detailed) list of volumes on a +server. +
AFS_VS_Lst1Vol +	None +	ECode AFSName HostID VolID +	AFSVolListOneVolume - Return header information for a single +volume. +
AFS_VS_XLst1Vl +	None +	ECode AFSName HostID VolID +	AFSVolXListOneVolume - Return (detailed) header information for a single +volume. +
AFS_VS_GetNVol +	None +	ECode AFSName HostID VolID +	AFSVolGetNthVolume - Get volume header given its index. +
AFS_VS_Monitor +	None +	ECode AFSName HostID +	AFSVolMonitor - Collect server transaction state. +
AFS_VS_SetInfo +	P O M +	ECode AFSName HostID Trans +	AFSVolSetInfo - Set volume status. +

Backup Server Events

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Event +	Class +	Parameters +	Description +
AFS_BUDB_Start +	P +	ECode +	The backup server has started. +
AFS_BUDB_Finish +	None +	ECode +	The backup server has finished. Finish events are rare since the +server process is normally aborted. +
AFS_BUDB_Exit +	None +	ECode +	The backup server has exited. Exit events are rare since the +server process is normally aborted. +
AFS_BUDB_CrDmp +	P O +	ECode AFSName HostID dumpId +	BUDB_CreateDump - Create a new dump. +
AFS_BUDB_AppDmp +	P +	ECode AFSName HostID dumpId +	BUDB_makeDumpAppended - Make the dump an appended dump. +
AFS_BUDB_DelDmp +	P O +	ECode AFSName HostID dumpId +	BUDB_DeleteDump - Delete a dump. +
AFS_BUDB_FinDmp +	P +	ECode AFSName HostID dumpId +	BUDB_FinishDump- Notify buserver that dump is finished. +
AFS_BUDB_UseTpe +	P M +	ECode AFSName HostID dumpId +	BUDB_UseTape - Create/add a tape entry to a dump. +
AFS_BUDB_DelTpe +	P M +	ECode AFSName HostID dumpId +	BUDB_DeleteTape - Remove a tape from the database. +
AFS_BUDB_FinTpe +	P +	ECode AFSName HostID dumpId +	BUDB_FinishTape - Writing to a tape is completed. +
AFS_BUDB_AddVol +	P M +	ECode AFSName HostID volId +	BUDB_AddVolume - Add a volume to a particular dump and tape. +
AFS_BUDB_GetTxV +	None +	ECode AFSName HostID Type +	BUDB_GetTextVersion - Get the version number for +hosts/volume-sets/dump-hierarchy. +
AFS_BUDB_GetTxt +	P +	ECode AFSName HostID Type +	BUDB_GetText - Get the information about +hosts/volume-sets/dump-hierarchy. +
AFS_BUDB_SavTxt +	M +	ECode AFSName HostID Type +	BUDB_SaveText - Overwrite the information about +hosts/volume-sets/dump-hierarchy. +
AFS_BUDB_GetLck +	None +	ECode AFSName HostID +	BUDB_GetLock - Take a lock for reading/writing text information. +
AFS_BUDB_FrALck +	None +	ECode AFSName HostID +	BUDB_FreeLock - Free a lock. +
AFS_BUDB_FreLck +	None +	ECode AFSName HostID +	BUDB_FreeAllLocks - Free all locks. +
AFS_BUDB_GetIId +	None +	ECode AFSName HostID +	BUDB_GetInstanceId - Get lock instance id. +
AFS_BUDB_DmpDB +	None +	ECode AFSName HostID +	BUDB_DumpDB - Start dumping the database. +
AFS_BUDB_RstDBH +	None +	ECode AFSName HostID +	BUDB_RestoreDbHeader - Restore the database header. +
AFS_BUDB_DBVfy +	None +	ECode AFSName HostID +	BUDB_DbVerify - Verify the database. +
AFS_BUDB_FndDmp +	P +	ECode AFSName HostID volName +	BUDB_FindDump - Find the dump a volume belongs to. +
AFS_BUDB_GetDmp +	P +	ECode AFSName HostID +	BUDB_GetDumps - Get a list of dumps in the database. +
AFS_BUDB_FnLTpe +	P +	ECode AFSName HostID dumpId +	BUDB_FindLastTape - Find last tape, and last volume on tape of a +dump. +
AFS_BUDB_GetTpe +	P +	ECode AFSName HostID +	BUDB_GetTapes - Find a list of tapes based on name or dump ID. +
AFS_BUDB_GetVol +	P +	ECode AFSName HostID +	BUDB_GetVolumes - Find a list of volumes based on dump or tape +name. +
AFS_BUDB_DelVDP +	P M +	ECode AFSName HostID dumpSetName +	BUDB_DeleteVDP - Delete dumps with given name and dump path. +
AFS_BUDB_FndCln +	P M +	ECode AFSName HostID volName +	BUDB_FindClone - Find clone time of volume. +
AFS_BUDB_FndLaD +	P +	ECode AFSName HostID volName +	BUDB_FindLatestDump - Find the latest dump a volume belongs to. +
AFS_BUDB_TGetVr +	None +	ECode AFSName HostID +	BUDB_T_GetVersion - Test Get version. +
AFS_BUDB_TDmpHa +	P +	ECode AFSName HostID file +	BUDB_T_DumpHashTable - Test dump of hash table. +
AFS_BUDB_TDmpDB +	P +	ECode AFSName HostID file +	BUDB_T_DumpDatabase - Test dump of database. +

Protection Server Events

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +

Event +	Class +	Parameters +	Description +
AFS_PTS_Start +	P +	ECode +	The protection server has started. +
AFS_PTS_Finish +	C +	ECode +	The protection server has finished. Finish events are rare since +the server process is normally aborted. +
AFS_PTS_Exit +	C +	ECode +	The protection server has exited. Exit events are rare since the +server process is normally aborted. +
AFS_PTS_NmToId +	None +	ECode AFSName HostID +	PR_NameToID - Perform one or more name-to-ID translations. +
AFS_PTS_IdToNm +	None +	ECode AFSName HostID GroupId +	PR_IDToName - Perform one or more ID-to-name translations. +
AFS_PTS_NewEnt +	None +	ECode AFSName HostID GroupId Name OwnerId +	PR_NewEntry - Create a PDB (Protection DataBase) entry for the given +name. +
AFS_PTS_INewEnt +	None +	ECode AFSName HostID GroupId Name OwnerId +	PR_INewEntry - Create a PDB entry for the given name and ID. +
AFS_PTS_LstEnt +	None +	ECode AFSName HostID GroupId +	PR_ListEntry - Get the contents of a PDB entry based on its ID. +
AFS_PTS_DmpEnt +	None +	ECode AFSName HostID Position +	PR_DumpEntry - Get the contents of a PDB entry based on its +offset. +
AFS_PTS_ChgEnt +	None +	ECode AFSName HostID GroupId NewName NewOwnerId NewId +	PR_ChangeEntry - Change an existing PDB entry's ID, name, owner, or +a combination. +
AFS_PTS_SetFEnt +	None +	ECode AFSName HostID GroupId +	PR_SetFieldsEntry - Change miscellaneous fields in an existing PDB +entry. +
AFS_PTS_Del +	None +	ECode AFSName HostID GroupId +	PR_Delete - Delete an existing PDB entry. +
FS_PTS_WheIsIt +	None +	ECode AFSName HostID GroupId Position +	PR_WhereIsIt - Get the PDB byte offset of the entry for a given +ID. +
AFS_PTS_AdToGrp +	None +	ECode AFSName HostID GroupId UserId +	PR_AddToGroup - Add a user to a group. +
AFS_PTS_RmFmGrp +	None +	ECode AFSName HostID GroupId UserId +	PR_RemoveFromGroup - Remove a user from a chosen group. +
AFS_PTS_LstMax +	None +	ECode AFSName HostID +	PR_ListMax - Get the largest allocated user and group ID. +
AFS_PTS_SetMax +	None +	ECode AFSName HostID GroupId flag +	PR_SetMax - Set the largest allocated user and group ID. +
AFS_PTS_LstEle +	None +	ECode AFSName HostID GroupId +	PR_ListElements - List all IDs associated with a user or group. +
AFS_PTS_GetCPS +	None +	ECode AFSName HostID GroupId +	PR_GetCPS - Get the CPS (Current Protection Subdomain) for the given +ID. +
AFS_PTS_GetCPS2 +	None +	ECode AFSName HostID GroupId Host +	PR_GetCPS2 - Get the CPS for the given id and host. +
AFS_PTS_GetHCPS +	None +	ECode AFSName HostID Host +	PR_GetHostCPS - Get the CPS for the given host. +
AFS_PTS_LstOwn +	None +	ECode AFSName HostID GroupId +	PR_ListOwned - Get all IDs owned by the given ID. +
AFS_PTS_IsMemOf +	None +	ECode AFSName HostID UserId GroupId +	PR_IsAMemberOf - Is a given user ID a member of a specified group? +

Authentication Events

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Event +	Class +	Parameters +	Description +
AFS_KAA_ChPswd +	S +	ECode AFSName HostID name instance +	KAA_ChangePassword - Change password. +
AFS_KAA_Auth +	A S +	ECode AFSName HostID name instance +	KAA_Authenticate - Authenticate to the cell. +
AFS_KAA_AuthO +	S +	ECode AFSName HostID name instance +	KAA_Authenticate_old - Old style authentication. +
AFS_KAT_GetTkt +	A S +	ECode AFSName HostID name instance +	KAT_GetTicket - An attempt was made to get an AFS ticket for some +principal listed in the Authentication Database. +
AFS_KAT_GetTktO +	S +	ECode AFSName HostID name instance +	KAT_GetTicket_old - An attempt was made to get an AFS ticket for some +principal listed in the Authentication Database. +
AFS_KAM_CrUser +	S P +	ECode AFSName HostID name instance +	KAM_CreateUser - Create a user. +
AFS_KAM_DelUser +	S P +	ECode AFSName HostID name instance +	KAM_DeleteUser - Delete a user. +
AFS_KAM_SetPswd +	S +	ECode AFSName HostID name instance +	KAM_SetPassword - Set the password for a user. +
AFS_KAM_GetPswd +	S +	ECode AFSName HostID name +	KAM_GetPassword - Get the password of a user. +
AFS_KAM_GetEnt +	S +	ECode AFSName HostID name instance +	KAM_GetEntry - The RPC made by the kas examine command to get +one entry from the Authentication Database (by index entry). +
AFS_KAM_LstEnt +	S +	ECode AFSName HostID index +	KAM_ListEntry - The RPC made to list one or more entries in the +Authentication Database. +
AFS_KAM_Dbg +	S +	ECode AFSName HostID +	KAM_Debug - The RPC that produces a debugging trace for the +Authentication Server. +
AFS_KAM_SetFld +	S P +	ECode AFSName HostID name instance flags date lifetime maxAssoc +	KAM_SetFields - The RPC used by the kas setfields command to +manipulate the Authentication Database. +
AFS_KAM_GetStat +	S +	ECode AFSName HostID +	KAM_GetStatus - An RPC used to get statistics on the Authentication +Server. +
AFS_KAM_GRnKey +	S +	ECode AFSName HostID +	KAM_GetRandomKey - An RPC used to generate a random encryption +key. +
AFS_UnlockUser +	S +	ECode AFSName HostID name instance +	KAM_Unlock - The RPC used to initiate the kas unlock +command. +
AFS_LockStatus +	None +	ECode AFSName HostID name instance +	KAM_LockStatus - The RPC used to determine whether a user's +Authentication Database entry is locked. +
AFS_UseOfPriv +	P +	ECode AFSName HostID name instance cell +	An authorized command was issued and allowed because the user had +privilege. +
AFS_UnAth +	S +	ECode AFSName HostID name instance cell +	An authorized command was issued and allowed because the system was +running in noauth mode. +
AFS_UDPAuth +	A S +	ECode name instance +	An authentication attempt was made with a Kerberos client. +
AFS_UDPGetTckt +	A S +	ECode name instance cell name instance +	An attempt was made to get a Kerberos ticket. +
AFS_RunNoAuth +	S +	ECode +	Check was made and some random server is running noauth. +
AFS_NoAuthDsbl +	S P +	ECode +	Server is set to run in authenticated mode. +
AFS_NoAuthEnbl +	S P +	ECode +	Server is set to run in unauthenticated mode. +

File Server and Cache Manager Interface Events

+
+ + + + + + + + + + + + + + + + + + + + + + +

Event +	Class +	Parameters +	Description +
AFS_SRX_FchACL +	None +	ECode AFSName HostID (FID) +	RXAFS_FetchACL - Fetch the ACL associated with the given AFS file +identifier. +
AFS_SRX_FchStat +	None +	ECode AFSName HostID (FID) +	RXAFS_FetchStatus - Fetch the status information for a file system +object. +
AFS_SRX_StACL +	M +	ECode AFSName HostID (FID) +	RXAFS_StoreACL - Associate an ACL with the names directory. +
AFS_SRX_StStat +	M +	ECode AFSName HostID (FID) +	RXAFS_StoreStatus - Store status information for the specified +file. +
AFS_SRX_RmFile +	O +	ECode AFSName HostID (FID) name +	RXAFS_RemoveFile - Delete the given file. +
AFS_SRX_CrFile +	O +	ECode AFSName HostID (FID) name +	RXAFS_CreateFile - Create the given file. +
AFS_SRX_RNmFile +	O M +	ECode AFSName HostID (oldFID) oldName (newFID) newName +	RXAFS_Rename - Rename the specified file in the given directory. +
AFS_SRX_SymLink +	O +	ECode AFSName HostID (FID) name +	RXAFS_Symlink - Create a symbolic link. +
AFS_SRX_Link +	O +	ECode AFSName HostID (FID) name (FID) +	RXAFS_Link - Create a hard link. +
AFS_SRX_MakeDir +	O +	ECode AFSName HostID (FID) name +	RXAFS_MakeDir - Create a directory. +
AFS_SRX_RmDir +	O +	ECode AFSName HostID (FID) name +	RXAFS_RemoveDir - Remove a directory. +
AFS_SRX_SetLock +	None +	ECode AFSName HostID (FID) type +	RXAFS_SetLock - Set an advisory lock on the given file identifier. +
AFS_SRX_ExtLock +	None +	ECode AFSName HostID (FID) +	RXAFS_ExtendLock - Extend an advisory lock on a file. +
AFS_SRX_RelLock +	None +	ECode AFSName HostID (FID) +	RXAFS_ReleaseLock - Release the advisory lock on a file. +
AFS_SRX_FchData +	None +	ECode AFSName HostID (FID) +	StartRXAFS_FetchData - Begin a request to fetch file data. +
AFS_SRX_StData +	O +	ECode AFSName HostID (FID) +	StartRXAFS_StoreData - Begin a request to store file data. +
AFS_SRX_BFchSta +	None +	ECode AFSName HostID (FID) +	RXAFS_BulkStatus - Fetch status information regarding a set of file +system objects. +
AFS_SRX_SetVolS +	M +	ECode AFSName HostID volId volName +	RXAFS_SetVolumeStatus - Set the basic status information for the named +volume. +
AFS_Priv +	P +	ECode viceId callRoutine +	Checking Permission Rights of user - user has permissions. +
AFS_PrivSet +	P +	ECode viceId callRoutine +	Set the privileges of a user. +

BOS Server Events

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Event +	Class +	Parameters +	Description +
AFS_BOS_CreBnod +	P C +	ECode AFSName HostID +	BOZO_CreateBnode - Create a process instance. +
AFS_BOS_DelBnod +	P C +	ECode AFSName HostID instance +	BOZO_DeleteBnode - Delete a process instance. +
AFS_BOS_SetReSt +	P M C +	ECode AFSName HostID +	BOZO_Restart - Restart a given process instance. +
AFS_BOS_GetLog +	P +	ECode AFSName HostID +	StartBOZO_GetLog - Pass the IN params when fetching a BOS Server log +file. +
AFS_BOS_SetStat +	P M C +	ECode AFSName HostID instance +	BOZO_SetStatus - Set process instance status and goal. +
AFS_BOS_SetTSta +	P M C +	ECode AFSName HostID instance +	BOZO_SetTStatus - Temporarily set process instance status and +goal. +
AFS_BOS_StartAl +	P C +	ECode AFSName HostID +	BOZO_StartupAll - Start all existing process instances. +
AFS_BOS_ShtdAll +	P C +	ECode AFSName HostID +	BOZO_ShutdownAll - Shut down all process instances. +
AFS_BOS_ReStAll +	P C +	ECode AFSName HostID +	BOZO_RestartAll - Shut down, then restart all process instances. +
AFS_BOS_ReBos +	P C +	ECode AFSName HostID +	BOZO_ReBozo - Shut down, then restart all process instances and the BOS +Server itself. +
AFS_BOS_ReBosIn +	P C +	ECode +	BOZO_ReBozo - Same as AFS_BOS_ReBos but done internally (server +restarts). +
AFS_BOS_ReStart +	P C +	ECode AFSName HostID instance +	BOZO_Restart - Restart a given process instance. +
AFS_BOS_WaitAll +	P C +	ECode AFSName HostID +	BOZO_WaitAll - Wait until all process instances have reached their +goals. +
AFS_BOS_AddSUsr +	S P +	ECode AFSName HostID +	BOZO_AddSUser - Add a user to the UserList. +
AFS_BOS_DelSUsr +	S P +	ECode AFSName HostID +	BOZO_DeleteSUser - Delete a user from the UserList. +
AFS_BOS_LstSUsr +	None +	ECode AFSName HostID +	BOZO_ListSUsers - Get the name of the user in the given position in the +UserList file. +
AFS_BOS_LstKey +	P +	ECode AFSName HostID +	BOZO_ListKeys - List information about the key at a given index in the +key file. +
AFS_BOS_LstKeyU +	P +	ECode AFSName HostID +	BOZO_ListKeys - Same as AFS_BOS_LstKey, but unauthorized. +
AFS_BOS_AddKey +	S P +	ECode AFSName HostID +	BOZO_AddKey - Add a key to the key file. +
AFS_BOS_DelKey +	S P +	ECode AFSName HostID +	BOZO_DeleteKey - Delete the entry for an AFS key. +
AFS_BOS_SetNoAu +	S P +	ECode AFSName HostID flag +	BOZO_SetNoAuthFlag - Enable or disable authenticated call +requirements. +
AFS_BOS_SetCell +	S P +	ECode AFSName HostID name +	BOZO_SetCellName - Set the name of the cell to which the BOS Server +belongs. +
AFS_BOS_AddHst +	S P +	ECode AFSName HostID name +	BOZO_AddCellHost - Add an entry to the list of database server +hosts. +
AFS_BOS_DelHst +	S P +	ECode AFSName HostID name +	BOZO_DeleteCellHost - Delete an entry from the list of database server +hosts. +
AFS_BOS_Inst +	P O M +	ECode AFSName HostID name +	+ StartBOZO_Install - Pass the IN parameters when installing a server +binary. + EndBOZO_Install - Get the OUT parameters when installing a server +binary. +
AFS_BOS_UnInst +	P O M +	ECode AFSName HostID name +	BOZO_UnInstall - Roll back from a server binary installation. +
AFS_BOS_PrnLog +	P O +	ECode AFSName HostID +	BOZO_Prune - Throw away old versions of server binaries and core +file. +
AFS_BOS_Exec +	P C +	ECode AFSName HostID cmd +	BOZO_Exec - Execute a shell command at the server. +
AFS_BOS_DoExec +	P C +	ECode exec +	The bosserver process was restarted. +
AFS_BOS_StpProc +	P C +	ECode cmd +	An RPC to stop any process controlled by the BOS Server. +

Volume Location Server Events

+
+ + + + + + + + + +

Event +	Class +	Parameters +	Description +
AFS_VL_CreEnt +	P M +	ECode AFSName HostID name +	VL_CreateEntry - Create a VLDB entry. +
AFS_VL_DelEnt +	P M +	ECode AFSName HostID volID +	VL_DeleteEntry - Delete a VLDB entry. +
AFS_VL_GetNVlID +	None +	ECode AFSName HostID +	VL_GetNewVolumeId - Generate a new volume ID. +
AFS_VL_RepEnt +	P M +	ECode AFSName HostID volID +	VL_ReplaceEntry - Replace entire contents of VLDB entry. +
AFS_VL_UpdEnt +	P M +	ECode AFSName HostID volID +	VL_UpdateEntry - Update contents of VLDB entry. +
AFS_VL_SetLck +	P +	ECode AFSName HostID volID +	VL_SetLock - Lock VLDB entry. +
AFS_VL_RelLck +	P +	ECode AFSName HostID volID +	VL_ReleaseLock - Unlock VLDB entry. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminGuide/auagd026.htm b/doc/html/AdminGuide/auagd026.htm new file mode 100644 index 0000000..35374a7 --- /dev/null +++ b/doc/html/AdminGuide/auagd026.htm @@ -0,0 +1,7140 @@ + + +Administration Guide + + + + + + + + + + + +

Administration Guide

Index

+A +B +C +D +E +F +G +H +I +J +K +L +M +N +O +P +Q +R +S +T +U +V +W +X +

+A + +

a ACL permission +(8032) +

A instruction + +

uss template file +(7695) +

access + +

permissions on ACL (see entries: permissions on ACL, ACL) +(8022) +

control list, see entry: ACL +(5594) +

count, in volume header +(6623) +

transparent (AFS feature) +(5558) +

ACL + +

adding entries +(8065) +

auxiliary permissions +(8041) +

cleaning +(8097) +

clearing +(8081) +

compared to UNIX protection +(8020) +

copying between directories +(8088) +

default on new volume +(6467) +

displaying +(8059) +

editing entries +(8064) +

foreign users on +(8058) +

group entries, usefulness +(8052) +

normal vs. negative permissions +(8048) +

permissions defined +(8024) +

removing entries +(8066) +

removing obsolete AFS IDs +(8093) +

replacing all entries +(8080) +

setting entries +(8063) +

setting for directory with uss +(7668) +

setting on user home directory with uss +(7659) +

shorthand notation for grouping permissions +(8042) +

system groups on +(8055) +

active + +

clients statistic from scout program +(7122) +

state of fstrace event set +(7158) +

adding + +

ACL entry + +

negative permissions +(8078) +

normal permissions +(8071) +

ADMIN flag to Authentication Database entry +(8135) +

CellServDB file (server) entry for database server machine +(6153) +

database server machine + +

to client CellServDB file and kernel memory +(7422) +

to server CellServDB file +(6150) +

disk to file server machine +(6202) +

members to groups +(7946) +

read-only site definition in VLDB +(6521) +

server encryption key to KeyFile file +(7280) +

system:administrators group members +(8117) +

UserList file users +(8155) +

ADMIN flag in Authentication Database entry + +

displaying +(8128) +

privileges resulting +(8124) +

setting or removing +(8134) +

administer ACL permission + +

see entry: a ACL permission +(8031) +

administering + +

client machine +(7309) +

server machine +(5841) +

user accounts +(7736) +

administrative database + +

about replicating +(6055) +

backing up +(6081) +

restoring +(6083) +

administrative privilege + +

three types +(8103) +

AFS + +

root directory (/afs) + +

on client machine +(5663) +

auditing events on AIX server machines +(7242) +

authentication separate from UNIX +(5756) +

differences from UNIX summarized +(5609) +

global namespace +(5660) +

initialization script +(7333) +

reducing traffic in +(5575) +

root directory (/afs) + +

in cell filespace +(5684) +

security features +(5814) +

server encryption key (see entry: server encryption key) +(7247) +

server processes used in +(5580) +

UID see entry: AFS UID +(5587) +

afs entry in Authentication Database + +

displaying +(7276) +

setting server encryption key +(7287) +

AFS GID + +

counter for automatic allocation, displaying and setting +(7998) +

definition +(7876) +

displaying + +

for all groups in Protection Database +(7904) +

for one group +(7856) +

removing obsolete from ACL +(8096) +

AFS UID + +

assigning + +

with pts createuser command +(7751) +

with uss +(7714) +

counter for automatic allocation, displaying and setting +(7997) +

definition +(7875) +

displaying + +

for all users and machines in Protection Database +(7903) +

for one user or machine +(7855) +

matching with UNIX UID +(7605), (7738) +

removing obsolete from ACL +(8095) +

reserved + +

anonymous user +(5736) +

system-defined groups +(5754) +

reusing, about +(7918) +

setting counters for automatic allocation +(8012) +

AFSCELL environment variable +(6975) +

AFSCONF environment variable (NFS/AFS Translator) +(8166) +

afsd program +(7318) +

afsmonitor program + +

available statistics +(8186) +

Cache Manager statistics +(8187) +

command syntax +(7205) +

creating an output file +(7204) +

creating configuration files for +(7202) +

features summarized +(7193) +

file server statistics +(8188) +

requirements for running +(7194) +

screen layout +(7201) +

setting terminal type +(7197) +

stopping +(7207) +

AFSSERVER environment variable (NFS/AFS Translator) +(8164) +

afszcm.cat file +(7339) +

AIX + +

auditing AFS events + +

about +(7243) +

list of available events +(8189) +

configuring tape device +(6857) +

all shorthand for ACL permissions +(8044) +

all-or-nothing release of read-only volumes +(6497) +

anonymous user + +

AFS UID reserved +(5735) +

identity assigned to unauthenticated user +(6177) +

archiving + +

tapes in Backup System +(6913) +

ASK instruction in CFG_device_name file +(6967) +

assigning + +

AFS GID to group +(7923) +

AFS UID to machine +(7915) +

AFS UID to user +(7753) +

AFS UID with uss +(7608) +

asynchrony + +

enabling for Cache Manager write operations +(7508) +

when AFS files saved on NFS clients +(8167) +

at-sys (@sys) variable in pathnames +(5728) +

auditing AFS events on AIX server machines +(7244) +

authenticated identity + +

acquiring with klog command +(5779) +

authentication + +

AFS compared to UNIX +(5613) +

AFS separate from UNIX +(5755) +

compared to authorization checking +(6174) +

consequences of multiple failures +(5799) +

improving security +(7763) +

Authentication Database + +

afs entry +(7262) +

changing username +(7784) +

entry + +

creating with kas create command +(7749) +

creating with uss +(7712) +

deleting with uss +(7723) +

removing +(7808) +

password + +

setting +(7777) +

password lifetime, setting +(5794), (7772) +

server encryption key + +

displaying +(7274) +

setting +(7285) +

site for AFS server encryption key +(7261) +

Authentication Server + +

about starting and stopping +(6315) +

as kaserver process +(6272) +

binary in /usr/afs/bin +(5874) +

description +(5586) +

displaying log file +(6422) +

restarting after adding entry to server CellServDB file +(6157) +

restarting after removing entry from server CellServDB file +(6168) +

runs on database server machine +(6024) +

when to contact +(6274) +

AuthLog file +(5994) + +

displaying +(6421) +

authorization checking + +

and restarting processes +(6182) +

compared to authentication +(6173) +

controlling cell-wide +(6180) +

defined +(6178) +

disabling +(6185) +

enabling +(6188) +

automatic + +

process restarts by BOS Server +(6395) +

update to admin. databases by Ubik +(6062) +

automating + +

tape mounting and unmounting by Backup System +(6962) +

creation of backup volumes +(6537) +

AUTOQUERY instruction in CFG_device_name file +(6966) +

auxiliary ACL permissions +(8040) +

availability of data + +

interrupted by dumping +(6764) +

+B + +

B instruction + +

package configuration file +(7554) +

backing up + +

administrative databases +(6082) +

Backup Database to tape +(7081) +

data from AFS volumes +(7019) +

backup commands + +

adddump +(6922) +

addhost +(6863) +

addvolentry +(6883) +

addvolset +(6879) +

binary in /usr/afs/bin +(5846) +

dbverify +(7084) +

deldump +(6933) +

deletedump +(7092) +

delhost +(6866) +

delvolentry +(6898) +

delvolset +(6893) +

diskrestore +(7073) +

dump +(7031) +

dumpinfo +(7036) +

granting privilege for +(8142) +

interactive mode + +

entering +(6982) +

exiting +(6989) +

jobs +(6994) +

kill +(6999) +

labeltape +(6947) +

listdumps +(6939) +

listhosts +(6872) +

listvolsets +(6888) +

quit +(6986) +

readlabel +(6949) +

restoredb +(7089) +

savedb +(7087) +

scantape +(7049) +

setexp +(6928) +

status +(7009) +

volinfo +(7042) +

volrestore +(7069) +

volsetrestore +(7075) +

Backup Database + +

administering +(7077) +

backing up +(7079) +

described +(6841) +

dump hierarchy + +

displaying +(6935) +

dump ID numbers, displaying +(7038) +

dump levels + +

adding +(6915) +

deleting +(6930) +

displaying +(6936) +

dump records + +

creating as part of dump operation +(7028) +

displaying +(7033) +

expiration dates +(6902) + +

changing +(6925) +

setting +(6919) +

port offset numbers + +

displaying +(6871) +

restoring +(7078) +

Tape Coordinator + +

adding entry +(6865) +

removing entry +(6869) +

verifying integrity +(7083) +

volume dump history + +

displaying +(7040) +

recovering from tapes +(7047) +

volume entry + +

creating +(6881) +

deleting from volume set +(6894) +

displaying +(6885) +

volume set + +

creating +(6876) +

deleting +(6890) +

displaying +(6884) +

Backup field in volume header +(6615) +

Backup Server + +

about starting and stopping +(6318) +

as buserver process +(6256) +

binary in /usr/afs/bin +(5860) +

description +(5605) +

displaying log file +(6423) +

restarting after adding entry to server CellServDB file +(6159) +

restarting after removing entry from server CellServDB file +(6170) +

runs on database server machine +(6023) +

when to contact +(6258) +

Backup System + +

automating operations +(6951) +

automating tape mounting and unmounting +(6959) +

Backup Database (see entry: Backup Database) +(6842) +

Backup Server described +(5604) +

configuration overview +(6843) +

data + +

backing up/dumping +(7012) +

recovering +(7056) +

restoring +(7055) +

dump (see entry: dump) +(6811) +

dump hierarchy (see entry: dump hierarchy) +(6821) +

dump history + +

recovering from tapes +(7046) +

dump ID number + +

assigning as part of dump operation +(7027) +

dump ID number (see entry: dump) +(6829) +

dump level (see entry: dump hierarchy) +(6822) +

dump name (see entry: dump) +(6827) +

dump operation, overview +(7024) +

dump records + +

deleting +(7091) +

dump set (see entry: dump set) +(6812) +

dumps, full and incremental defined +(7014) +

eliminating check for proper tape name +(6971) +

eliminating search/prompt for initial tape +(6963) +

filemarks (see entry: Tape Coordinator) +(6835) +

interactive mode +(6978) + +

canceling operations +(6997) +

displaying pending/running operations +(6991) +

interfaces +(6974) +

introduction +(6805) +

job ID numbers + +

about +(6981) +

displaying +(6992) +

port offsets (see entry: Tape Coordinator) +(6839) +

recycling schedule for tapes +(6907) +

reducing operator intervention +(6952) +

regular expressions +(6875) +

restores + +

date-specific +(7058) +

full +(7057) +

restoring + +

backed up data +(7062) +

backup data +(7063) +

data +(7054) +

running in foreign cell +(6977) +

scanning tapes +(7044) +

suggestions for improving efficiency +(7023) +

Tape Coordinator (see entry: Tape Coordinator) +(6838) +

tape name (see entry: tapes) +(6828) +

useCount counter on tape label +(6910) +

using default responses to errors +(6968) +

volume dump history + +

recovering from tapes +(7048) +

volume entry (see entry: volume entry) +(6810) +

volume set (see entry: volume set) +(6809) +

backup volume + +

automating creation of +(6538) +

changing name of +(6786) +

creating +(6533) +

creating multiple at once +(6536) +

defined +(6435) +

dumping +(6763) +

ID number in volume header +(6611) +

mounting +(6544) +

moving +(6680) +

removed by read/write move +(6678) +

removed by read/write removal +(6745) +

space-saving nature of +(6481) +

suggested schedule for creation of +(6540) +

BackupLog file +(5996) + +

displaying +(6419) +

BAK version of binary file + +

created by bos install command +(6098) +

removing obsolete +(6121) +

used by bos uninstall command +(6109) +

banner line on the scout program screen +(7116) +

basenames in scout program +(7112) +

bdb.DB0 file +(5973) +

bdb.DBSYS1 file +(5975) +

binary distribution machine + +

defined +(6027) +

identifying with bos status +(6046) +

block special device + +

creating with package +(7557) +

bos commands + +

install +(6101) +

addhost +(6160) +

addkey + +

basic instructions +(7289) +

when handling key emergency +(7306) +

adduser +(8156) +

binary in /usr/afs/bin +(5848) +

create +(6344) +

delete +(6354) +

exec +(6246) +

getdate +(6119) +

getlog +(6428) +

getrestart +(6404) +

granting privilege for +(8140) +

listhosts +(6144) +

listkeys +(7273) +

listusers +(8152) +

mutual authentication, bypassing +(6193) +

prune +(6130) +

removehost +(6171) +

removekey +(7297) +

removeuser +(8160) +

restart + +

excluding BOS Server +(6384) +

including BOS Server +(6382) +

selected processes +(6388) +

with -bosserver flag +(6381) +

salvage +(6709) +

setauth +(6183) +

setrestart +(6407) +

shutdown +(6372) +

start +(6370) +

startup +(6374) +

status +(6328) +

stop +(6364) +

summary of functions +(6255) +

uninstall +(6111) +

BOS Server + +

as bosserver process +(6250) +

binary in /usr/afs/bin +(5854) +

description +(5583) +

displaying log file +(6424) +

maintainer of server process binaries +(6087) +

memory state +(6312) +

monitoring server processes +(6248) +

restart times, displaying and setting +(6394) +

role in reboot of server machine +(6244) +

use of BosConfig file +(6311) +

when to contact +(6253) +

BosConfig file +(5950) + +

changing status flag from NotRun to Run +(6368) +

changing status flag from Run to NotRun +(6362) +

creating server process entry +(6343) +

displaying entries +(6327) +

information +(6295) +

removing server process entry +(6350) +

restart times defined +(6403) +

BosLog file +(5998) + +

displaying +(6420) +

bosserver + +

(see entry: BOS Server) +(5850) +

binary in /usr/afs/bin +(5849) +

bulk mode in uss +(7729) +

buserver + +

(see entry: Backup Server) +(5856) +

binary in /usr/afs/bin +(5855) +

butc command +(7005) +

+C + +

C instruction + +

package configuration file +(7558) +

cache files (client) +(7344) +

Cache Manager + +

afsd initialization program +(7319) +

as interpreter of mount points +(6456) +

CellServDB file (client), using +(7405) +

collecting data with xstat data collection facility +(7214) +

configuring and customizing +(7310) +

data cache + +

displaying size set at reboot +(7359) +

data cache size + +

displaying current +(7379) +

resetting to default value (for disk cache only) +(7399) +

setting in cacheinfo file +(7385) +

setting until next reboot +(7391) +

database server processes, contacting +(7404) +

described +(7312) +

displaying + +

cache size from cacheinfo file +(7357) +

enabling asynchrony for write operations +(7510) +

flushing cache +(7455) +

functions of +(5608) +

interfaces registered with File Server +(7482) +

messages displayed, controlling +(7498) +

monitoring performance +(7099) +

preference ranks for File Server and VL Server +(7469) +

setting + +

cache size in cacheinfo file +(7358) +

disk cache location +(7356) +

home cell +(7450) +

probe interval for File Server +(7444) +

setuid programs +(7436) +

system type name stored in kernel memory +(7502) +

use of NetInfo file +(7480) +

use of NetRestrict file +(7481) +

xstat data collection facility libraries +(7216) +

xstat data collections +(7222) +

xstat example commands +(7233) +

xstat_cm_test example command +(7240) +

cacheinfo file +(7324) + +

displaying contents +(7361) +

format +(7387) +

resetting disk cache to size specified +(7397) +

setting + +

cache size +(7362) +

disk cache location +(7360) +

CacheItems file +(7346) +

caching +(5574) +

callback +(5578) +

cell +(5552) + +

changing list in client kernel memory +(7427) +

filespace configuration issues +(5681) +

foreign +(5556) +

granting local access to foreign users +(5679) +

local +(5554) +

making foreign visible to local +(5675) +

making local visible to foreign +(5668) +

name + +

at second level in file tree +(5665), (5667), (5686) +

choosing +(5648) +

setting +(5655) +

setting home cell for client machine +(7447) +

CellServDB file (client) + +

about +(7325), (7400) +

central update source for clients +(7413) +

changing +(7429) +

copied into kernel memory +(7407) +

correct format +(7409) +

displaying +(7415) +

global source from AFS Support +(7414) +

maintaining +(7412) +

updating with or without package +(7431) +

CellServDB file (server) + +

about +(5937) +

adding database server machine +(6152) +

displaying +(6146) +

effect of wrong information in +(6140) +

importance to Ubik operation +(6065) +

maintaining +(6135) +

removing database server machine +(6164) +

CellServDB file maintained by AFS Product Support + +

as global update source +(5672) +

CellServDB.local file +(5674) +

cellular mount point + +

see entry: mount point +(6557) +

CFG_device_name file +(6953) +

changing + +

ACL entries +(8067) +

data cache size specified in cacheinfo file +(7363) +

data cache size temporarily +(7389) +

disk cache location, in cacheinfo file +(7364) +

disk cache size to default value +(7395) +

group ownership to self-owned +(7945) +

group-creation quota +(7984) +

mount point when renaming user +(7800) +

Protection Database entry + +

name +(7972) +

owner +(7967) +

username +(7781) +

volume name +(6782) +

volume name when renaming user +(7795) +

character special device + +

creating with package +(7561) +

checksum +(7266) +

chgrp command + +

AFS compared to UNIX +(5620) +

chmod command + +

AFS compared to UNIX +(5615) +

choosing + +

name + +

cell +(5649) +

user +(5734) +

user volume +(5738) +

user volume mount point +(5740) +

chown command + +

AFS compared to UNIX +(5618) +

clearing + +

all ACL entries +(8084) +

contents of trace log (fstrace) +(7190) +

client + +

configuring local disk with package +(7520) +

definition +(5547) +

machine + +

definition +(5550) +

modifying to run package +(7578) +

client machine + +

/usr/vice/etc directory +(7317) +

administering +(7308) +

cache files +(7345) +

CellServDB file, displaying +(7418) +

changing CellServDB file +(7428) +

changing list of cells in kernel memory +(7426) +

configuration files +(7316) +

configuration issues +(5722) +

controlling running of setuid programs +(7435) +

data cache size + +

displaying current +(7378) +

setting in cacheinfo file +(7384) +

setting until next reboot +(7390) +

data cache size set at reboot + +

displaying +(7366) +

database server machines, displaying knowledge of +(7419) +

database server processes, contacting +(7403) +

disk cache size + +

resetting to default value +(7398) +

disk versus memory cache +(7354) +

displaying + +

data cache size from cacheinfo file +(7367) +

enabling access to foreign cell +(5727) +

files required on local disk +(5724) +

flushing data cache +(7460) +

making foreign cell visible +(5678) +

messages displayed, controlling +(7499) +

monitoring performance +(7100) +

setting + +

data cache size in cacheinfo file +(7368) +

disk cache location +(7365) +

home cell +(7451) +

setting home cell +(5657) +

system type name stored in Cache Manager memory +(7503) +

client machines statistic from scout program +(7123) +

clocks + +

need to synchronize for Ubik +(6066) +

clone +(5573), (6479) + +

forcing creation of new +(6504) +

cloning + +

defined +(6478) +

for backup +(6530) +

for replication +(6487) +

close system call + +

for files saved on AFS client +(5645) +

for files saved on NFS client +(8173) +

cm event set (fstrace) +(7156) +

cmfx trace log (fstrace) +(7154) +

collecting + +

data with xstat data collection facility +(7212) +

command interpreters + +

CellServDB file (client), using +(7406) +

command parameters + +

in BosConfig file +(6310) +

command suite + +

binaries + +

displaying time stamp +(6114) +

installing +(6093) +

removing obsolete +(6125) +

uninstalling +(6107) +

commands + +

afsd +(7321) +

afsmonitor +(7206) +

backup + +

to enter interactive mode +(6983) +

backup adddump +(6923) +

backup addhost +(6862) +

backup addvolentry +(6882) +

backup addvolset +(6878) +

backup dbverify +(7085) +

backup deldump +(6934) +

backup deletedump +(7093) +

backup delhost +(6867) +

backup delvolentry +(6897) +

backup delvolset +(6892) +

backup diskrestore +(7074) +

backup dump +(7032) +

backup dumpinfo +(7037) +

backup interactive +(6984) +

backup jobs +(6995) +

backup kill +(7000) +

backup labeltape +(6948) +

backup listdumps +(6940) +

backup listhosts +(6873) +

backup listvolsets +(6889) +

backup quit +(6987) +

backup readlabel +(6950) +

backup restoredb +(7088) +

backup savedb +(7086) +

backup scantape +(7050) +

backup setexp +(6929) +

backup status +(7010) +

backup volinfo +(7043) +

backup volrestore +(7070) +

backup volsetrestore +(7076) +

bos addhost +(6161) +

bos addkey +(7290) +

bos adduser +(8157) +

bos create +(6345) +

bos delete +(6355) +

bos exec +(6245) +

bos getdate +(6120) +

bos getlog +(6429) +

bos getrestart +(6405) +

bos install +(6102), (6112) +

bos listhosts +(6145) +

bos listkeys +(7272) +

bos listusers +(8153) +

bos prune +(6129) +

bos removehost +(6172) +

bos removekey +(7296) +

bos removeuser +(8161) +

bos restart + +

excluding BOS Server +(6385) +

including BOS Server +(6383) +

selected processes +(6389) +

bos salvage +(6710) +

bos setauth +(6184) +

bos setrestart +(6408) +

bos shutdown +(6371) +

bos start +(6369) +

bos startup +(6373) +

bos status +(6329) +

bos stop +(6365) +

butc +(7006) +

chgrp (AFS compared to UNIX) +(5621) +

chmod (AFS compared to UNIX) +(5616) +

chown (AFS compared to UNIX) +(5619) +

executing from uss template file +(7701) +

fms +(6852) +

fs checkservers +(7446) +

fs checkvolumes +(7466) +

fs cleanacl +(8098) +

fs copyacl +(8092) +

fs examine +(6661), (6737) +

fs exportafs +(8179) +

fs flush +(7462) +

fs flushmount +(7468) +

fs flushvolume +(7464) +

fs getcacheparms +(7382) +

fs getcellstatus +(7439) +

fs getclientaddrs +(7495) +

fs getserverprefs +(7476) +

fs listacl +(8062) +

fs listcells +(7421) +

fs listquota +(6655), (6726) +

fs lsmount +(6564) +

fs messages +(7501) +

fs mkmount +(6476) + +

general instructions +(6570) +

when changing username +(7802) +

when creating user account +(7761) +

when mounting backup volume +(6548) +

when renaming volume +(6791) +

when restoring volume +(6776) +

fs newcell +(7434) +

fs quota +(6722) +

fs rmmount +(6578), (6757), (6789), (7797), (7814) +

fs setacl +(8074) + +

with -clear flag +(8087) +

with -negative flag +(8076) +

fs setcachesize +(7393) +

fs setcell +(7441) +

fs setclientaddrs +(7497) +

fs setquota +(6716) +

fs setserverprefs +(7478) +

fs setvol +(6720) +

fs storebehind + +

displaying asynchrony for specific files +(7518) +

displaying default asynchrony +(7516) +

setting asynchrony for specific files +(7514) +

setting default asynchrony +(7512) +

fs sysname +(7505) +

fs whereis +(6668) +

fsck (AFS compared to UNIX) +(5637) +

fsck (AFS version) +(5639) +

fstrace clear +(7188) +

fstrace dump +(7183) +

fstrace lslog +(7179) +

fstrace lsset +(7175) +

fstrace setlog +(7167) +

fstrace setset +(7171) +

ftp (AFS compared to UNIX) +(5829) +

ftpd (AFS compared to UNIX) +(5623), (5831) +

groups (AFS compared to UNIX) +(5625) +

inetd (AFS compared to UNIX) +(5627), (5833) +

kas create +(7757) + +

when changing username +(7790) +

kas delete +(7807) + +

when changing username +(7788) +

kas examine +(7278) + +

to display ADMIN flag +(8131) +

kas interactive +(6198) +

kas setfields +(5793), (5798) + +

limiting failed authentication attempts +(7767) +

prohibiting password reuse +(7774) +

setting ADMIN flag +(8132) +

setting password lifetime +(7771) +

kas setpassword +(5789), (7292), (7779) +

kas unlock +(7769) +

klog +(5774) +

klog with -setpag flag +(5760) +

klog.krb +(5807) +

knfs +(8183) +

kpasswd +(5787), (5802), (5803) +

ln (AFS compared to UNIX) +(5629) +

mount +(8180) +

package +(7581) +

pagsh +(5758) +

pagsh.krb +(5808) +

privileged, defined +(6176) +

pts adduser +(7952) + +

for system:administrators group +(8119) +

pts chown +(7970) +

pts creategroup +(7939) +

pts createuser + +

machine entry +(7920) +

user account +(7755) +

pts delete +(7818), (7966) +

pts examine +(7874) +

pts listentries +(7912) +

pts listmax +(8000) +

pts listowned +(7894) +

pts membership +(7886) + +

displaying system:administrators group +(8115) +

pts removeuser +(7959) + +

for system:administrators group +(8123) +

pts rename + +

machine or group name +(7977) +

username +(7786) +

pts setfields + +

setting group creation quota +(7986) +

setting privacy flags +(7994) +

pts setmax +(8015) +

rcp (AFS compared to UNIX) +(5631), (5835) +

rlogind (AFS compared to UNIX) +(5633), (5837) +

rsh (AFS compared to UNIX) +(5635), (5839) +

scout +(7147) +

share +(8177) +

strings +(6132) +

sys +(7507) +

tokens +(5772) +

tokens.krb +(5809) +

udebug +(5904) +

umount +(6219) +

unlog +(5781) +

uss add +(7717) +

uss bulk +(7735) +

uss delete +(7726) +

vos addsite +(6523) +

vos backup +(6546) +

vos backupsys +(6550) +

vos changeaddr +(6241) +

vos create + +

basic instructions +(6473) +

when creating user account +(7759) +

vos delentry +(6752) +

vos dump +(6770) +

vos examine + +

basic instructions +(6633) +

vos listaddrs +(6239) +

vos listpart +(6207) +

vos listvldb + +

syntax +(6586) +

vos listvol + +

syntax +(6600) +

vos lock +(6799) +

vos move + +

basic instructions +(6681) +

vos partinfo +(6470) +

vos release + +

basic instructions +(6527) +

vos remove +(7810) + +

basic instructions +(6755) +

vos remsite +(6750) +

vos rename + +

basic instructions +(6787) +

when changing username +(7792) +

vos restore +(6774), (6778) +

vos syncserv +(6699) +

vos syncvldb +(6697) +

vos unlock +(6801) +

vos unlockvldb +(6803) +

vos zap +(6748) +

which +(6131) +

xstat_cm_test +(7238) +

xstat_fs_test +(7234) +

common configuration files (server) +(5934) +

compilation + +

date of, listing on binary file +(6117) +

compiling + +

package prototype file +(7575) +

configuration file + +

instructions for package program +(7541) +

see entry: CFG_<device_name> configuration file +(6956) +

configuration files + +

client machine +(7315) +

package program +(7529) +

server machine, common +(6032) +

configuring + +

afsmonitor program +(7203) +

Cache Manager +(7311) +

client machine, issues +(5723) +

file server machine, issues +(5707) +

filespace, issues +(5682) +

local disk of client with package +(7519) +

trace log (fstrace) +(7169) +

Conn statistic from scout program +(7119) +

consistency guarantees + +

administrative databases +(6070) +

cached data +(5579) +

constants + +

uss template file +(7626) +

contacting processes + +

Authentication Server +(6275) +

Backup Server +(6259) +

BOS Server +(6254) +

File Server +(6267) +

NTPD +(6284) +

Protection Server +(6279) +

Salvager +(6271) +

Update Server +(6289) +

VL Server +(6293) +

Volume Server +(6269) +

controlling + +

authorization checking for entire cell +(6179) +

server machine interfaces registered in VLDB +(6228) +

conventions + +

AFS pathnames +(5662) +

cell name +(5650) +

volume names +(5692), (6461) +

converting + +

existing UNIX accounts to AFS accounts + +

with manual account creation +(7742) +

with uss +(7618) +

coordinator (Ubik) + +

defined +(6060) +

coordinator (Ubik) + +

election procedure described +(6073) +

copying + +

ACL between directories +(8090) +

core files + +

for server processes +(5993) +

removing from /usr/afs/logs directory +(6127) +

core leak + +

preventing with scheduled restarts +(6392) +

correspondence + +

of volumes and directories +(5563) +

corruption + +

symptoms and types +(6702) +

counter + +

Protection Database (max user id, max group id) +(7995) +

CPS +(7822) +

creating + +

ACL as copy of another +(8089) +

ACL entry +(8070) +

ACL entry in negative permissions section +(8077) +

Authentication Database entry + +

with kas create command +(7747) +

with uss +(7710) +

backup volume +(6531) +

cellular mount point +(6572) +

common local password file with uss +(7612) +

directory with uss +(7665) +

file with uss +(7673), (7679) +

group, self-owned +(7944) +

link (hard or symbolic) with uss +(7687) +

mount point when changing username +(7803) +

mount point with uss +(7654) +

multiple backup volumes at once +(6534) +

NetInfo file (client version) +(7488) +

NetInfo file (server version) +(6233) +

NetRestrict file (client version) +(7492) +

NetRestrict file (server version) +(6236) +

PAG with klog or pagsh command +(5763) +

Protection Database group entry +(7921) +

Protection Database machine entry +(7913) +

Protection Database user entry + +

with pts createuser command +(7746) +

with uss +(7709) +

read-only volume +(6486) +

read/write or regular mount point +(6566) +

read/write volume +(6463) +

server encryption key +(7282) +

server process +(6331) +

standard files in new user account +(5745) +

tape label (Backup System) +(6945) +

user account + +

with uss +(7705) +

with individual commands +(7744) +

user account types with uss +(7625) +

user accounts in bulk with uss +(7727) +

volume with uss +(7644) +

creation date + +

recorded in volume header +(6619) +

creator + +

Protection Database entry + +

displaying +(7858) +

displaying all +(7906) +

criteria for replicating volumes +(6508) +

cron process + +

creating with bos create command +(6348) +

cron server process + +

defining in BosConfig file +(6341) +

cron-type server process + +

defined +(6304) +

used to automate volume backup +(6542) +

current protection subgroup +(7821) +

curses graphics utility + +

afsmonitor program +(7195) +

scout program requirements +(7105) +

+D + +

d ACL permission +(8030) +

D instruction + +

package configuration file +(7542) +

uss template file +(7667) +

daily restart for new binaries + +

displaying and setting time +(6399) +

data + +

availability interrupted by dumping +(6765) +

data cache + +

changing location of disk cache +(7372) +

disk cache size + +

resetting to default value +(7394) +

disk versus memory +(7353) +

displaying size specified in cacheinfo file +(7374) +

flushing (forcing update) +(7454) +

size + +

current, displaying +(7377) +

recommendations +(7355) +

set at reboot, displaying +(7373) +

setting in cacheinfo file +(7371), (7383) +

setting until next reboot +(7388) +

Vn file in +(7352) +

data collection + +

with xstat data collection facility +(7211) +

database files +(5968) +

database server machine + +

adding + +

to client CellServDB file and kernel memory +(7424) +

to server CellServDB file +(6151) +

CellServDB file (client), displaying +(7417) +

CellServDB file (server) entry + +

adding +(6154) +

removing +(6165) +

client knowledge of +(7402) +

defined +(6021) +

displaying list in server CellServDB file +(6148) +

identifying with bos status +(6040) +

maintaining +(6056) +

reason to run three +(5711) +

removing + +

from client CellServDB file and kernel memory +(7425) +

from server CellServDB file +(6163) +

use of NetInfo and NetRestrict files +(6225) +

database server process + +

about starting and stopping +(6314) +

need to run all on every database server machine +(6064) +

restarting after adding entry to server CellServDB file +(6155) +

restarting after removing entry from server CellServDB file +(6166) +

use of CellServDB file +(6137) +

database, distributed + +

see entry: administrative database +(6053) +

databases, distributed +(5713) +

date + +

on binary file, listing +(6116) +

date-specific restores +(7060) +

default + +

ACL +(6466) +

volume quota +(6469), (6712) +

defining + +

directory for even distribution of accounts with uss +(7639) +

read-only site in VLDB +(6520) +

server encryption key +(7281) +

server encryption key in Authentication Database +(7286) +

server process in BosConfig file +(6332) +

delayed write operations + +

when AFS files saved on NFS clients +(8169) +

delete ACL permission + +

see entry: d ACL permission +(8029) +

deleting + +

Authentication Database entry with uss +(7721) +

Protection Database user entry with uss +(7720) +

user accounts in bulk with uss +(7730) +

user accounts with uss +(7718) +

denying + +

file access with negative ACL entry +(8079) +

desynchronization of VLDB/volume headers + +

fixing +(6693) +

symptoms of +(6689) +

determining + +

identity of database server machines +(6041) +

identity of binary distribution machine +(6047) +

identity of system control machine +(6044) +

identity of: + +

simple file server machines +(6050) +

roles taken by server machine +(6036) +

success of replication +(6495) +

differences + +

between AFS and UNIX, summarized +(5611) +

directories + +

/afs +(5664), (5685) +

/afs/cellname +(5666), (5687) +

/usr/afs/backup +(6861) +

conventional under /afs/cell_name +(5690) +

for grouping user home directories +(5741) +

lost+found +(5640) +

directories (server) + +

/usr/afs/bin +(6089) +

directory + +

/usr/afs/bin on server machines +(5843) +

/usr/afs/db on server machines +(5967) +

/usr/afs/etc +(5932) +

/usr/afs/local on server machines +(5947) +

/usr/afs/logs on server machines +(5989) +

/usr/vice/cache +(7342) +

/usr/vice/etc +(7314) +

/vicep on server machines +(6009) +

correspondence with volume +(5562) +

creating with package +(7545) +

creating with uss +(7666) +

defining for even distribution of accounts with uss +(7640) +

disk cache +(7343) +

flushing from data cache on client machine +(7457) +

overwritten by uss if exists +(7600) +

root +(5569) +

directory-level data protection + +

implications +(8021) +

directory/file name + +

translating to volume ID number +(6659) +

translating to volume location +(6665) +

translating to volume name +(6653) +

disabling + +

authorization checking +(6187) +

discarding + +

tokens +(5782) +

disk + +

file server machine + +

adding/installing +(6204) +

removing +(6214) +

local (see entry: local disk) +(7521) +

Disk attn statistic from scout program +(7128) +

disk partition + +

displaying size of single +(6736) +

grouping related volumes on +(5701) +

monitoring usage of +(7125) +

moving volumes to reduce overcrowding +(6672) +

display layout in scout program window +(7114) +

displaying + +

ACL entries +(8060) +

ADMIN flag in Authentication Database entry +(8129) +

AFS user id and max group id counters +(8004) +

BOS Server's automatic restart times +(6406) +

Cache Manager preference ranks for file server machines +(7471) +

CellServDB file (client) +(7416) +

CellServDB file (server) +(6147) +

client interfaces registered with File Server +(7485) +

contents of trace log (fstrace) +(7185) +

counters for AFS UID and AFS GID +(8003) +

creator of Protection Database entry +(7839), (7897) +

data cache size + +

set at reboot +(7369) +

specified in cacheinfo file +(7370) +

data cache size, current +(7380) +

database server machines in server CellServDB file +(6149) +

disk partition size +(6735) +

entries from BosConfig file +(6325) +

group-creation quota in Protection Database entry +(7842) +

groups owned by a user or group +(7888) +

groups to which user or machine belongs +(7878) +

KeyFile file +(7269) +

log files for server processes +(6413) +

members of group +(7879) +

membership count in Protection Database entry +(7841) +

mount point +(6560), (6561) +

owner of Protection Database entry +(7838), (7896) +

privacy flags on Protection Database entry +(7840) +

Protection Database entries (all) +(7895) +

Protection Database entry +(7837) +

server encryption key from Authentication Database +(7275) +

server encryption keys in KeyFile file +(7271) +

server entries from VLDB +(6229) +

server process status +(6322) +

state of event set (fstrace) +(7177) +

state of trace log (fstrace) +(7181) +

system:administrators group members +(8113) +

tape label (Backup System) +(6946) +

time stamp on binary file +(6118) +

UserList file +(8151) +

VLDB entry + +

with volume header +(6626) +

VLDB entry with volume header +(6627) +

VLDB server entries +(6230) +

volume header +(6598) + +

with VLDB entry +(6630) +

volume header with VLDB entry +(6631) +

volume information +(6580) +

volume quota + +

percent used +(6724) +

with volume & partition info +(6732) +

with volume size +(6728) +

volume size +(6730), (6733) +

volume's VLDB entry +(6582) +

distributed database + +

see entry: administrative database +(6054) +

distributed databases +(5714) +

distributed file system +(5544) + +

security issues +(5821) +

distribution + +

of CellServDB file (server) +(6142) +

of databases +(5712), (6052) +

dormant (state of fstrace event set) +(7160) +

dumb terminal + +

use in scout program +(7109) +

use with afsmonitor +(7199) +

dump (Backup System) + +

appended + +

creating +(7030) +

appended, defined +(6813) +

creating Backup Database record +(7029) +

defined +(6815) +

displaying Backup Database record +(7034) +

full, defined +(6816) +

ID number, described +(6831) +

ID number, displaying +(7035) +

incremental, defined +(6817) +

initial, defined +(6818) +

label, described +(6834) +

name, described +(6832) +

parent, defined +(6814) +

set (see entry: dump set) +(6819) +

dump hierarchy (Backup System) + +

creating +(6899) +

described +(6824) +

displaying +(6937) +

dump level + +

defined +(6825) +

dump levels + +

adding +(6917) +

deleting +(6932) +

expiration date on dump level + +

described +(6826) +

expiration dates +(6903) + +

assigning to dump levels +(6900) +

changing +(6926) +

setting +(6920) +

dump ID number (Backup System) + +

displaying +(7039) +

dump ID numbers (Backup System) +(7025) +

dump levels + +

defined +(6823) +

expiration dates +(6904) + +

changing +(6927) +

setting +(6921) +

in Backup Database + +

adding +(6916) +

deleting +(6931) +

displaying +(6938) +

dump set (Backup System) + +

creating +(7013) +

defined +(6820) +

deleting from Backup Database +(7090) +

full dumps +(7015) +

incremental dumps +(7016) +

dumping + +

Backup Database to tape +(7080) +

data +(7020) +

dump ID numbers +(7026) +

full dumps +(7021) +

incremental dumps +(7022) +

trace log contents (fstrace) +(7186) +

volumes + +

reasons +(6766) +

using vos command +(6769) +

without using AFS Backup System +(6759) +

dynamic kernel loader programs + +

directory for AFS library files +(7337) +

+E + +

E instruction + +

uss template file +(7683) +

editing + +

NetInfo file (client version) +(7489) +

NetInfo file (server version) +(6234) +

NetRestrict file (client version) +(7493) +

NetRestrict file (server version) +(6237) +

election of Ubik coordinator +(6074) +

emergency + +

server encryption keys mismatched +(7298) +

enabling authorization checking +(6189) +

encrypted network communication +(5816) +

entering + +

kas interactive mode +(6199) +

entry in VLDB + +

displaying, with volume header +(6629) +

for volume +(6443) +

locking/unlocking +(6796) +

environment + +

types compared +(5540) +

erasing + +

all ACL entries +(8083) +

etc/exports file +(8174) +

etc/fstab file + +

(see entry: file systems registry file) +(6211) +

event set (fstrace) + +

cm +(7157) +

displaying state +(7176) +

persistence +(7163) +

setting +(7172) +

events + +

auditing AFS on AIX server machines +(7245) +

examples + +

library files for package +(7539) +

prototype files for package +(7535) +

scout program display +(7153) +

uss template file +(7636) +

executing + +

command using uss template line +(7700) +

expiration dates +(6901) + +

absolute +(6905) +

changing +(6924) +

relative +(6906) +

setting +(6918) +

+F + +

F instruction + +

package configuration file +(7546) +

uss template file +(7677) +

failure + +

of file storage due to full partition +(6675) +

of uss account creation + +

recovering from +(7595) +

Fetch statistic from scout program +(7120) +

file + +

creating standard ones in new user account +(5743) +

creating with package +(7549) +

creating with uss +(7674), (7680) +

flushing from data cache on client machine +(7456) +

overwritten by uss if exists +(7601) +

required on client machine local disk +(5726) +

file extension + +

.BAK +(6096) +

.OLD +(6097) +

File Server + +

as part of fs process +(6262), (6301) +

binary in /usr/afs/bin +(5866) +

client interfaces registered +(7483) +

collecting data with xstat data collection facility +(7213) +

CPS requested from Protection Server +(7824) +

description +(5582) +

displaying log file +(6425) +

interfaces registered in VLDB + +

listed in sysid file +(5964) +

interfaces registered in VLDB server entry +(6226) +

monitoring with scout program +(7138) +

use of NetInfo file +(6221) +

use of NetRestrict file +(6222) +

use of sysid file +(6223) +

when to contact +(6266) +

xstat data collection facility libraries +(7215) +

xstat data collections +(7221) +

xstat example commands +(7232) +

xstat_fs_test example command +(7236) +

file server machine +(5548) + +

partitions, naming +(6012) +

Cache Manager preference ranks for +(7470) +

configuration files in /usr/afs/local +(5949) +

core files in /usr/afs/logs +(5990) +

database files in /usr/afs/db +(5971) +

disk + +

adding/installing +(6205) +

removing +(6215) +

displaying log files +(6410) +

installing command and process binaries +(6094) +

log files in /usr/afs/logs +(5991) +

monitoring outages of +(7139) +

rebooting, about +(5718) +

restoring partitions using Backup System +(7053) +

salvaging volumes +(6706) +

file server probe interval + +

setting for a client machine +(7442) +

file storage + +

failed due to partition crowding +(6676) +

file system + +

defined +(5543) +

monitoring activity +(7101) +

salvager (see entry: Salvager) +(6265) +

file systems registry file + +

adding new disk to file server machine +(6210) +

removing disk from file server machine +(6220) +

file tree + +

conventions + +

for configuring +(5683) +

third level +(5689) +

creating volumes to match top level directories +(5694) +

FileLog file +(6001) + +

displaying +(6415) +

files + +

/usr/afs/etc/KeyFile +(7258) +

AFS initialization script +(7334) +

AFS libraries used by dynamic kernel loader programs +(7338) +

afsd +(7320) +

afszcm.cat +(7340) +

AuthLog +(5995) +

backup command binary +(5845) +

BackupLog +(5997) +

bdb.DB0 +(5972) +

bdb.DBSYS1 +(5974) +

bos command binary +(5847) +

BosConfig +(5951), (6296) +

BosLog +(5999) +

bosserver binary +(5851) +

buserver +(5857) +

cacheinfo +(7323) +

CacheItems +(7347) +

CellServDB (client) +(7326) +

CellServDB (server) +(5938), (6136) +

CellServDB file (client) +(7401) +

CellServDB.local +(5673) +

CFG_<device_name> +(6954) +

displaying log files +(6414) +

exports +(8175) +

file systems registry (fstab) +(6209) +

FileLog +(6000) +

fileserver +(5863) +

fms.log +(6850) +

FORCESALVAGE +(6016) +

global CellServDB +(5671) +

kas command binary +(5867) +

kaserver binary file +(5871) +

kaserver.DB0 +(5976) +

kaserver.DBSYS1 +(5978) +

KeyFile +(5940) +

NetInfo (client version) +(7328), (7486) +

NetInfo (server version) +(5953) +

NetRestrict (client version) +(7330), (7490) +

NetRestrict (server version) +(5955) +

NoAuth +(5957) +

ntpd +(5876) +

ntpdc +(5882) +

package Makefile +(7571) +

prdb.DB0 +(5980) +

prdb.DBSYS1 +(5982) +

pts command binary +(5884) +

ptserver binary +(5888) +

runntp +(5894) +

SALVAGE.fs +(5959) +

salvage.lock +(5961) +

SalvageLog +(6002) +

salvager +(5898) +

server configuration, in /usr/afs/etc directory +(5933) +

sysid +(5963) +

tapeconfig +(6847) +

ThisCell (client) +(7332) +

ThisCell (server) +(5943) +

udebug +(5903) +

upclient +(5908) +

upserver +(5914) +

UserList +(5945) +

V.vol_ID.vol +(6014) +

vldb.DB0 +(5984) +

vldb.DBSYS1 +(5986) +

VLLog +(6005) +

vlserver +(5918) +

Vn +(7350) +

VolserLog +(6007) +

volserver +(5925) +

VolumeItems +(7348) +

vos command binary +(5929) +

fileserver + +

(see entry: File Server) +(5862) +

binary in /usr/afs/bin +(5861) +

flexible synchronization site (Ubik) +(6075) +

flushing + +

data cache on client machine +(7453) +

fms command +(6853) +

fms.log file +(6849) +

FORCESALVAGE file +(6015) +

foreign cell +(5555) + +

making local cell visible +(5670) +

making visible in local cell +(5677) +

format of CellServDB file (client) +(7410) +

fs commands + +

examine +(6662) +

lsmount +(6565) +

setquota +(6717) +

setvol +(6721) +

whereis +(6669) +

checkservers +(7445) +

checkvolumes +(7465) +

cleanacl +(8099) +

copyacl +(8091) +

examine +(6738) +

exportafs +(8178) +

flush +(7461) +

flushmount +(7467) +

flushvolume +(7463) +

getcacheparms +(7381) +

getcellstatus +(7438) +

getclientaddrs +(7494) +

getserverprefs +(7475) +

granting privilege for +(8106) +

listacl +(8061) +

listcells +(7420) +

listquota +(6656), (6727) +

messages +(7500) +

mkmount + +

for read/write volume +(6477) +

general instructions +(6571) +

when changing username +(7801) +

when creating user account +(7760) +

when mounting backup volume +(6549) +

when renaming volume +(6792) +

when restoring volume +(6777) +

mutual authentication, bypassing +(6201) +

newcell +(7433) +

quota +(6723) +

rmmount +(6579) + +

when changing username +(7796) +

when removing user account +(7813) +

when removing volume +(6758) +

when renaming volume +(6790) +

setacl +(8073) + +

with -clear flag +(8086) +

with -negative flag +(8075) +

setcachesize +(7392) +

setcell +(7440) +

setclientaddrs +(7496) +

setserverprefs +(7477) +

storebehind + +

displaying asynchrony for specific files +(7517) +

displaying default asynchrony +(7515) +

setting asynchrony for specific files +(7513) +

setting default asynchrony +(7511) +

sysname +(7504) +

fs process +(6260) + +

creating +(6347) +

fs server process + +

defining in BosConfig file +(6342) +

fs-type server process + +

defined +(6299) +

fsck command + +

AFS compared to UNIX +(5636) +

AFS version +(5638) +

fstab file + +

(see entry: file systems registry file) +(6212) +

fstrace commands + +

clear +(7187) +

dump +(7182) +

example of use +(7192) +

lslog +(7178) +

lsset +(7174) +

privilege requirements +(7165) +

setlog +(7166) +

setset +(7170) +

fsync system call + +

for files saved on AFS client +(5644) +

for files saved on NFS client +(8172) +

ftpd command + +

AFS compared to UNIX +(5622), (5830) +

full dump +(7017) + +

creating using vos command +(6767) +

full restores +(7059) +

+G + +

global namespace +(5661) +

granting + +

file access by setting ACL +(8069) +

privilege for backup commands +(8148) +

privilege for bos commands +(8146) +

privilege for fs commands +(8109) +

privilege for kas commands +(8127), (8139) +

privilege for pts commands +(8110) +

privilege for vos commands +(8147) +

group + +

Protection Database entry + +

name, changing +(7975) +

ACL entry, usefulness of +(8051) +

AFS GID +(5746) +

AFS GID, assigning +(7925) +

creation quota (see entry: quota) +(7863) +

definition +(5595) +

group use +(7936) +

groups owned, displaying +(7887) +

members, adding +(7947) +

members, displaying +(7880) +

members, removing +(7954) +

membership of machine or user, displaying +(7881) +

name, assigning +(7926) +

orphaned, displaying +(7889) +

owned by user or group, displaying +(7892) +

owner + +

displaying +(7862) +

displaying for all +(7908) +

privacy flags +(5748) +

privacy flags on Protection Database entry + +

displaying +(7864) +

setting +(7987) +

private use +(7932) +

Protection Database entry + +

deleting +(7962) +

displaying +(7861) +

displaying all +(7907) +

Protection Database entry, creating +(7924) +

Protection Database entry, described +(7829) +

regular and prefix-less, defined +(7927) +

restrictions +(5747) +

rules for naming +(7942) +

self-owned, creating +(7943) +

shared use +(7934) +

system +(7832) +

system-defined +(5753) +

system-defined on ACLs +(8054) +

using effectively +(7930) +

group use of group +(7935) +

groups command + +

AFS compared to UNIX +(5624) +

+H + +

handling + +

server encryption key emergency +(7302) +

hard link + +

AFS restrictions on +(5642) +

creating with uss +(7688) +

overwritten by uss if exists +(7602) +

highlighting statistics in scout display + +

setting thresholds +(7149) +

use of reverse video +(7132) +

+I + +

i ACL permission +(8028) +

identifying + +

binary distribution machine +(6048) +

database server machine +(6042) +

roles taken by server machine +(6037) +

simple file server machine +(6051) +

system control machine +(6045) +

inactive (state of fstrace event set) +(7159) +

incremental dump + +

creating using vos command +(6768) +

creating with Backup System +(7018) +

inetd command + +

AFS compared to UNIX +(5626), (5832) +

initialization script for AFS +(7335) +

initializing + +

scout program +(7145) +

server process +(6330) +

insert ACL permission + +

see entry: i ACL permission +(8027) +

installing + +

disk on file server machine +(6203) +

server binaries +(6091) +

server process binaries, about +(6085) +

intention flag in VLDB entry +(6686) +

interactive mode (Backup System) + +

entering +(6985) +

exiting +(6988) +

features +(6979) +

operations + +

canceling pending/running +(6996) +

displaying pending/running +(6990) +

interactive mode (kas commands) +(6200) +

Internet + +

conventions for cell name +(5651) +

Network Information Center +(5652) +

+J + +

job ID numbers (Backup System) +(6980) + +

displaying +(6993) +

operations + +

canceling +(6998) +

+K + +

k ACL permission +(8038) +

kas commands + +

binary in /usr/afs/bin +(5868) +

create +(7756) + +

when changing username +(7789) +

delete + +

when changing username +(7787) +

when removing user account +(7806) +

examine + +

to display ADMIN flag +(8130) +

examine, to inspect afs key +(7279) +

granting privilege for +(8125) +

interactive +(6197) +

mutual authentication, bypassing +(6194) +

setfields +(5792), (5797) + +

limiting failed authentication attempts +(7766) +

prohibiting password reuse +(7773) +

setting ADMIN flag +(8133) +

setting password lifetime +(7770) +

setpassword +(5788), (5804), (7291), (7778) +

setpassword , when handling key emergency +(7307) +

unlock +(7768) +

kaserver process + +

(see entry: Authentication Server) +(5870) +

binary in /usr/afs/bin +(5869) +

kaserver.DB0 file +(5977) +

kaserver.DBSYS1 file +(5979) +

Kerberos + +

support for in AFS +(5806) +

use of usernames +(5590) +

kernel memory (client) + +

CellServDB file, reading into +(7408) +

key version number + +

defined +(7255) +

KeyFile file + +

adding server encryption key +(7284) +

displaying +(7268) +

function of +(5939) +

removing server encryption key +(7295) +

storage site for server encryption keys +(7257) +

klog command +(5775) + +

limiting failed attempts +(7765) +

when handling key emergency +(7305) +

with -setpag flag +(5761) +

klog.krb command +(5810) +

knfs command +(8182) +

kpasswd command +(5786), (5801) +

kpwvalid program +(5805) +

kvno + +

see entry: key version number +(7256) +

+L + +

l ACL permission +(8026) +

L instruction + +

package configuration file +(7550) +

uss template file +(7684) +

learning + +

volume ID + +

given directory/file name +(6658) +

given volume name +(6636) +

volume location + +

given directory/file name +(6664) +

given volume name/ID number +(6646) +

volume name + +

given directory/file name +(6652) +

given volume ID number +(6641) +

length restriction on volume names +(6460) +

library files in package +(7533) + +

constructing +(7568) +

examples +(7537) +

libxstat_cm.a library +(7218) + +

data collections +(7225) +

example command using +(7231) +

obtaining more information +(7228) +

routines +(7220) +

xstat_cm_test example command +(7239) +

libxstat_fs.a library +(7217) + +

data collections +(7224) +

example command using +(7230) +

obtaining more information +(7227) +

routines +(7219) +

xstat_fs_test example command +(7235) +

listing + +

tokens held by issuer +(5773) +

ln command + +

AFS compared to UNIX +(5628) +

local cell +(5553) + +

granting foreign users access to +(5680) +

making foreign cells visible in +(5676) +

making visible to foreign cells +(5669) +

local configuration files (server) +(5948) +

local disk + +

configuring on client, using package +(7522) +

files required on client machine +(5725) +

protecting on file server machine +(5716) +

local password file + +

creating common source version with uss +(7613), (7615) +

creating entry for AFS user + +

with manual account creation +(7737) +

with uss +(7604) +

setting password in + +

with manual account creation +(7741) +

with uss +(7611) +

when not using AFS-modified login utility +(5769) +

when using AFS--modified login utility +(5766) +

location + +

setting for client +(7375) +

standard for uss template file +(7632) +

lock ACL permission + +

see entry: k ACL permission +(8037) +

locked VLDB entry + +

displaying +(6585) +

unlocking +(6798) +

locking + +

VLDB entry +(6793), (6794) +

log files + +

displaying +(6412) +

fms.log +(6851) +

for replicated databases +(5970) +

for server processes +(5992) +

limiting failed attempts +(7764) +

AFS version +(5765) +

AFS version's interaction with local password file +(5767) +

lookup ACL permission + +

see entry: l ACL permission +(8025) +

lost+found directory +(5641) +

+M + +

machine + +

adding to group +(7950) +

AFS UID, assigning +(7917) +

group memberships + +

displaying number +(7865) +

group memberships, displaying +(7883) +

privacy flags on Protection Database entry + +

displaying +(7867) +

setting +(7989) +

Protection Database entry + +

deleting +(7964) +

displaying +(7866) +

displaying all +(7909) +

name, changing +(7976) +

Protection Database entry, creating +(7916) +

Protection Database entry, described +(7827) +

removing from group +(7957) +

mainframe + +

computing environment +(5541) +

maintaining + +

CellServDB file (client) +(7411) +

synchrony of VLDB with volume headers +(6449) +

majority + +

defined for Ubik +(6078) +

Makefile for package +(7570) + +

modifying +(7573) +

mapping + +

AFS ID to group, machine, or username +(7851) +

group name to AFS GID +(7854) +

machine name to AFS UID +(7853) +

username to AFS UID +(7852) +

max group id counter (Protection Database) + +

displaying +(8002) +

setting +(8006) +

max user id counter (Protection Database) + +

displaying +(8001) +

setting +(8005) +

maximum volume quota +(6713) +

MaxQuota field in volume header +(6618) +

members + +

group, adding +(7948) +

group, displaying +(7859), (7884) +

group, removing +(7955) +

membership + +

system groups +(7833) +

memory state of BOS Server +(6313) +

message line in scout program display +(7130) +

mode bits (UNIX) + +

interpretation in AFS +(8102) +

modifying + +

clients to run package +(7580) +

package Makefile +(7574) +

monitoring + +

Cache Manager performance +(7098) +

Cache Manager processes with afsmonitor +(7097) +

disk usage with scout program +(7126) +

file server processes with afsmonitor +(7096) +

file server processes with scout +(7095) +

outages with scout program +(7137) +

server processes +(6247) +

mount command +(8181) +

MOUNT instruction in CFG_device_name file +(6958) +

mount point + +

cellular + +

creating +(6574) +

described +(6558) +

changing when renaming user +(7798) +

choosing name for user volume +(5739) +

creating cellular +(6573) +

creating multiple per volume +(6457) +

creating read/write or regular +(6567) +

creating with uss +(7656) +

defined +(6452) +

definition +(5567) +

displaying +(6562) +

distinguishing different types +(6563) +

flushing from data cache on client machine +(7459) +

read/write + +

creating +(6569) +

described +(6556) +

regular + +

creating +(6568) +

described +(6554) +

removing +(6577), (6742) +

removing when removing user account +(7815) +

mounting + +

backup volume +(6543) +

disk on file server machine +(6206) +

foreign volume in local cell +(6559) +

read-only volume +(6512) +

read/write volume +(6474) +

volume + +

about +(6454) +

general instructions +(6552) +

moving + +

volume +(6670) +

mutual authentication +(5820) + +

failure due to mismatched keys +(7300) +

preventing +(6191) +

server encryption key's role +(7248) +

+N + +

name + +

Protection Database entry + +

changing +(7973) +

NAME_CHECK instruction in CFG_device_name file +(6970) +

needs salvage status flag in volume header +(6606) +

negative ACL permissions + +

defined +(8050) +

NetInfo file (client version) +(7327), (7487) +

NetInfo file (server version) +(5952) + +

creating/editing +(6232) +

NetRestrict file (client version) +(7329), (7491) +

NetRestrict file (server version) +(5954) + +

creating/editing +(6235) +

network + +

as computing environment +(5539) +

defined +(5538) +

encrypted communication in AFS +(5815) +

reducing traffic through caching +(5576) +

Network Information Center (for Internet) +(5653) +

Network Time Protocol Daemon + +

(see entry: NTPD) +(5880) +

New release + +

status flag on site definition in VLDB entry +(6597) +

New release site flag in VLDB + +

as indicator of failed replication +(6502) +

NFS/AFS Translator +(8162) + +

AFSCONF environment variable +(8165) +

NoAuth file +(5956) + +

creating in emergencies +(7303) +

none shorthand for ACL permissions +(8045) +

normal ACL permissions + +

defined +(8049) +

Not released + +

status flag on site definition in VLDB entry +(6595) +

NotRun status flag in BosConfig file + +

changing to Run +(6366) +

defined +(6308) +

NTPD +(5879) +

ntpd + +

binary in /usr/afs/bin +(5875) +

description +(5607) +

invoked by runntp process +(6281) +

when to contact +(6283) +

ntpdc + +

binary in /usr/afs/bin +(5881) +

number variables + +

uss template file +(7630) +

+O + +

Off-line status flag in volume header +(6605) +

Old release + +

status flag on site definition in VLDB entry +(6596) +

Old release site flag in VLDB + +

as indicator of failed replication +(6503) +

OLD version of binary file + +

created by bos install command +(6099) +

removing obsolete +(6122) +

used by bos uninstall command +(6110) +

OldFiles directory + +

as mount point for backup volume +(6545) +

On-line status flag in volume header +(6604) +

orphaned group +(7890) +

outages + +

BOS Server role in, +(5585) +

due to automatic server restart +(6401) +

due to server process restart +(6377) +

due to Ubik election +(6079) +

monitoring with scout program +(7135) +

overcrowding of disk partition + +

effect on users +(6674) +

moving volumes to reduce +(6673) +

overwriting + +

existing directories/files/links with uss +(7599) +

owner + +

Protection Database entry + +

changing +(7968) +

displaying +(7857) +

displaying all +(7905) +

rules for assigning +(7940) +

+P + +

package + +

B instruction in configuration file +(7555) +

C instruction in configuration file +(7559) +

compiling prototype files +(7527), (7576) +

configuration file instructions +(7540) +

configuration files +(7528) +

constructing prototype and library files +(7566) +

D instruction in configuration file +(7543) +

defining block special device in configuration file +(7556) +

defining character special device in configuration file +(7560) +

defining directory in configuration file +(7544) +

defining file in configuration file +(7548) +

defining socket in configuration file +(7564) +

defining symbolic link in configuration file +(7552) +

directory structure +(7530) +

example library files +(7536) +

example prototype files +(7531) +

F instruction in configuration file +(7547) +

L instruction in configuration file +(7551) +

library files +(7534) +

Makefile +(7569) +

modifying clients to run +(7579) +

modifying the Makefile +(7572) +

preparing prototype files +(7525), (7538) +

prototype file +(7523) +

S instruction in configuration file +(7563) +

to update client +(7430) +

package command +(7582) +

package directory +(7577) +

PAG + +

creating with klog or pagsh command +(5762) +

pagsh command +(5759) +

pagsh.krb command +(5811) +

participation + +

in AFS global namespace +(5659) +

partition + +

housing AFS volumes +(6011) +

restoring contents using Backup System +(7052) +

restoring using Backup System + +

to a new location +(7072) +

to the same location +(7071) +

salvaging all volumes +(6708) +

passwd file + +

see entry: local password file +(7616) +

password + +

AFS compared to UNIX +(5614) +

changing in AFS +(5785) +

checking quality of +(5800) +

consequences of multiple failed authentication attempts +(5796) +

expiration +(5790) +

improving security +(7762) +

lifetime +(5791) +

local password file +(5768) +

restricting reuse +(5795) +

setting in Authentication Database +(7775) +

setting in local password file + +

with manual account creation +(7740) +

with uss +(7610) +

permissions on ACL + +

defined +(8023) +

persistent fstrace event set or trace log +(7161) +

personal + +

computing environment +(5542) +

workstation + +

as typical AFS machine +(5551) +

possible variations + +

on replication +(6516) +

prdb.DB0 file +(5981) +

prdb.DBSYS1 file +(5983) +

preferences + +

setting +(7479) +

prefix-less group + +

see entry: group +(7929) +

preventing + +

core leaks, with scheduled BOS Server restarts +(6393) +

mutual authentication +(6192) +

previewing + +

user account creation/deletion with uss +(7590) +

privacy flags on Protection Database entry +(5749) + +

displaying +(7860) +

setting +(7991) +

private use of group +(7931) +

privilege + +

granting for backup commands +(8145) +

granting for bos commands +(8143) +

granting for fs commands +(8108) +

granting for kas commands +(8126) +

granting for pts commands +(8107) +

granting for vos commands +(8144) +

required for afsmonitor program +(7200) +

required for fstrace commands +(7164) +

required for scout program +(7110) +

required for uss commands +(7587) +

see entry: administrative privilege +(8104) +

privileged commands +(6175) +

process + +

lightweight Ubik +(6068) +

status flag in BosConfig file +(6309) +

process authentication group + +

see entry: PAG +(5764) +

processes + +

Authentication Server, binary in /usr/afs/bin +(5873) +

Backup Server, binary in /usr/afs/bin +(5859) +

BOS Server, binary in /usr/afs/bin +(5853) +

File Server, binary in /usr/afs/bin +(5865) +

NTPD, binary in /usr/afs/bin +(5878) +

Protection Server, binary in /usr/afs/bin +(5890) +

Salvager, binary in /usr/afs/bin +(5900) +

Update Server, binaries in /usr/afs/bin +(5910) +

VL Server, binary in /usr/afs/bin +(5920) +

Volume Server, binary in /usr/afs/bin +(5927) +

programs + +

afsd +(7322) +

bosserver +(5852) +

buserver +(5858) +

fileserver +(5864) +

kaserver +(5872) +

ntpd +(5877) +

ntpdc +(5883) +

ptserver +(5889) +

runntp +(5895) +

salvager +(5899) +

udebug +(5905) +

upclient +(5909) +

upserver +(5915) +

vlserver +(5919) +

volserver +(5926) +

protection + +

AFS compared to UNIX +(5612) +

in AFS +(5591) +

in UNIX +(5593) +

Protection Database +(5596) + +

user entry + +

deleting +(7819) +

changing username +(7783) +

creator of entry + +

displaying +(7848) +

creator of entry + +

displaying for all +(7902) +

entry name + +

changing +(7974) +

entry, deleting +(7961) +

group creation quota + +

displaying +(7850) +

setting +(7980), (7982) +

group entry +(7830) + +

displaying +(7844) +

displaying all +(7898) +

group entry, creating +(7922) +

ID counters, setting +(8009) +

machine entry + +

displaying +(7845) +

displaying all +(7899) +

machine entry, creating +(7914) +

machine entry, described +(7828) +

max user id and max group id counters, displaying and setting +(7996) +

membership count + +

displaying +(7843) +

owner of entry + +

changing +(7969) +

displaying +(7847) +

displaying for all +(7901) +

privacy flags + +

displaying +(7849) +

setting +(7992) +

setting + +

counters for AFS UIDs +(8011) +

user entry + +

creating with uss +(7711) +

creating with pts createuser command +(7748) +

deleting with uss +(7722) +

displaying +(7846) +

displaying all +(7900) +

user entry, described +(7825) +

protection of file data + +

AFS compared to UFSACL +(8017), (8019) +

Administration Reference

+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 +

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. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf002.htm b/doc/html/AdminReference/auarf002.htm new file mode 100644 index 0000000..82f7c3c --- /dev/null +++ b/doc/html/AdminReference/auarf002.htm @@ -0,0 +1,314 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

Tables
+

About This Manual
+

How to Use This Document +

Organization +

AuthLog.dir, AuthLog.pag +

AFS System Files
+

afs_file_intro +

AuthLog +

BosLog +

FORCESALVAGE +

NoAuth +

SALVAGE.fs +

SalvageLog +

TE_device_name +

Vn +

VLLog +

bdb.DB0 and bdb.DBSYS1 +

fms.log +

kaserverauxdb +

salvage.lock +

afsmonitor Configuration File +

AFS System Commands
+

afsd +

bos +

butc +

dlog +

dpass +

fms +

fs +

fs help +

kas +

kas noauthentication +

kdb +

klog +

knfs +

pts +

runntp +

rxdebug +

scout +

sys +

translate_et +

udebug +

up +

upclient +

upserver +

uss +

volinfo +

vos +

Index
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf003.htm b/doc/html/AdminReference/auarf003.htm new file mode 100644 index 0000000..d747b3a --- /dev/null +++ b/doc/html/AdminReference/auarf003.htm @@ -0,0 +1,29 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

Tables

File Server configuration parameters

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf004.htm b/doc/html/AdminReference/auarf004.htm new file mode 100644 index 0000000..7a2b088 --- /dev/null +++ b/doc/html/AdminReference/auarf004.htm @@ -0,0 +1,28 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

About This Manual

This chapter describes the purpose, organization, and conventions of this +document. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf005.htm b/doc/html/AdminReference/auarf005.htm new file mode 100644 index 0000000..09e908a --- /dev/null +++ b/doc/html/AdminReference/auarf005.htm @@ -0,0 +1,32 @@ + + +Administration Reference + + + + + + + + + + + +

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 + + + + diff --git a/doc/html/AdminReference/auarf006.htm b/doc/html/AdminReference/auarf006.htm new file mode 100644 index 0000000..b8cf388 --- /dev/null +++ b/doc/html/AdminReference/auarf006.htm @@ -0,0 +1,55 @@ + + +Administration Reference + + + + + + + + + + + +

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 + + + + diff --git a/doc/html/AdminReference/auarf007.htm b/doc/html/AdminReference/auarf007.htm new file mode 100644 index 0000000..6a0db0b --- /dev/null +++ b/doc/html/AdminReference/auarf007.htm @@ -0,0 +1,28 @@ + + +Administration Reference + + + + + + + + + + + +

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 + + + + diff --git a/doc/html/AdminReference/auarf008.htm b/doc/html/AdminReference/auarf008.htm new file mode 100644 index 0000000..be5907d --- /dev/null +++ b/doc/html/AdminReference/auarf008.htm @@ -0,0 +1,56 @@ + + +Administration Reference + + + + + + + + + + + +

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 + + + + diff --git a/doc/html/AdminReference/auarf010.htm b/doc/html/AdminReference/auarf010.htm new file mode 100644 index 0000000..c7ab21a --- /dev/null +++ b/doc/html/AdminReference/auarf010.htm @@ -0,0 +1,26 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

AFS System Files

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf011.htm b/doc/html/AdminReference/auarf011.htm new file mode 100644 index 0000000..68416fe --- /dev/null +++ b/doc/html/AdminReference/auarf011.htm @@ -0,0 +1,124 @@ + + +Administration Reference + + + + + + + + + + + +

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. +

Related Information +

Configuration files: + +

Administrative files: + +

Cache-related files: + +

Vn +

VolumeItems +

Log files: + +

AuthLog +

BackupLog +

BosLog +

VLLog +

fms.log +

Database files: + +

bdb.DB0 and bdb.DBSYS1 +

kaserverauxdb +

+ +

Controller files: +

FORCESALVAGE +

NoAuth +

SALVAGE.fs +

salvage.lock +

Volume header files: +

Vvol_ID.vol +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf012.htm b/doc/html/AdminReference/auarf012.htm new file mode 100644 index 0000000..3912009 --- /dev/null +++ b/doc/html/AdminReference/auarf012.htm @@ -0,0 +1,57 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

AuthLog

Purpose + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf013.htm b/doc/html/AdminReference/auarf013.htm new file mode 100644 index 0000000..92d7192 --- /dev/null +++ b/doc/html/AdminReference/auarf013.htm @@ -0,0 +1,49 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

AuthLog.dir, AuthLog.pag

Purpose + + + +

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 +

kdb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf014.htm b/doc/html/AdminReference/auarf014.htm new file mode 100644 index 0000000..b8565b3 --- /dev/null +++ b/doc/html/AdminReference/auarf014.htm @@ -0,0 +1,57 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

BackupLog

Purpose + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf015.htm b/doc/html/AdminReference/auarf015.htm new file mode 100644 index 0000000..d440166 --- /dev/null +++ b/doc/html/AdminReference/auarf015.htm @@ -0,0 +1,57 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

BosLog

Purpose + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf016.htm b/doc/html/AdminReference/auarf016.htm new file mode 100644 index 0000000..e1b4f7e --- /dev/null +++ b/doc/html/AdminReference/auarf016.htm @@ -0,0 +1,179 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

BosConfig

Purpose + + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf017.htm b/doc/html/AdminReference/auarf017.htm new file mode 100644 index 0000000..5e74b04 --- /dev/null +++ b/doc/html/AdminReference/auarf017.htm @@ -0,0 +1,59 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

CacheItems

Purpose + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf018.htm b/doc/html/AdminReference/auarf018.htm new file mode 100644 index 0000000..ef3cc76 --- /dev/null +++ b/doc/html/AdminReference/auarf018.htm @@ -0,0 +1,565 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

CFG_device_name

Purpose + + + + + +

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}]
+   
+

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. +

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. +

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. +

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 + + + + diff --git a/doc/html/AdminReference/auarf019.htm b/doc/html/AdminReference/auarf019.htm new file mode 100644 index 0000000..6438249 --- /dev/null +++ b/doc/html/AdminReference/auarf019.htm @@ -0,0 +1,120 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

CellServDB (client version)

Purpose + + + + + + + + +

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 +

fs newcell +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf020.htm b/doc/html/AdminReference/auarf020.htm new file mode 100644 index 0000000..f627a2b --- /dev/null +++ b/doc/html/AdminReference/auarf020.htm @@ -0,0 +1,91 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

CellServDB (server version)

Purpose + + + + + + + + +

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 +

IBM AFS Quick Beginnings +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf021.htm b/doc/html/AdminReference/auarf021.htm new file mode 100644 index 0000000..afdfa2f --- /dev/null +++ b/doc/html/AdminReference/auarf021.htm @@ -0,0 +1,57 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

FileLog

Purpose + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf022.htm b/doc/html/AdminReference/auarf022.htm new file mode 100644 index 0000000..d7672ec --- /dev/null +++ b/doc/html/AdminReference/auarf022.htm @@ -0,0 +1,49 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

FORCESALVAGE

Purpose + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf023.htm b/doc/html/AdminReference/auarf023.htm new file mode 100644 index 0000000..5a453fc --- /dev/null +++ b/doc/html/AdminReference/auarf023.htm @@ -0,0 +1,73 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

KeyFile

Purpose + + + + + + + + +

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 +

Related Information +

IBM AFS Administration Guide +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf024.htm b/doc/html/AdminReference/auarf024.htm new file mode 100644 index 0000000..cbf4430 --- /dev/null +++ b/doc/html/AdminReference/auarf024.htm @@ -0,0 +1,70 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

NetInfo (client version)

Purpose + + + + + + +

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 +

fs getclientaddrs +

fs setclientaddrs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf025.htm b/doc/html/AdminReference/auarf025.htm new file mode 100644 index 0000000..8cbc6cd --- /dev/null +++ b/doc/html/AdminReference/auarf025.htm @@ -0,0 +1,67 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

NetInfo (server version)

Purpose + + + + + +

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 +

vos listaddrs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf026.htm b/doc/html/AdminReference/auarf026.htm new file mode 100644 index 0000000..2c65fc7 --- /dev/null +++ b/doc/html/AdminReference/auarf026.htm @@ -0,0 +1,60 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

NetRestrict (client version)

Purpose + + + + + + +

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 +

fs getclientaddrs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf027.htm b/doc/html/AdminReference/auarf027.htm new file mode 100644 index 0000000..d808177 --- /dev/null +++ b/doc/html/AdminReference/auarf027.htm @@ -0,0 +1,71 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

NetRestrict (server version)

Purpose + + + + + +

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. +

To display the File Server interface addresses registered in the VLDB, use +the vos listaddrs command. +

Related Information +

vos listaddrs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf028.htm b/doc/html/AdminReference/auarf028.htm new file mode 100644 index 0000000..a8b1534 --- /dev/null +++ b/doc/html/AdminReference/auarf028.htm @@ -0,0 +1,67 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

NoAuth

Purpose + + + +

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 +

bos setauth +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf029.htm b/doc/html/AdminReference/auarf029.htm new file mode 100644 index 0000000..15d50b5 --- /dev/null +++ b/doc/html/AdminReference/auarf029.htm @@ -0,0 +1,58 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

SALVAGE.fs

Purpose + + + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf030.htm b/doc/html/AdminReference/auarf030.htm new file mode 100644 index 0000000..8568920 --- /dev/null +++ b/doc/html/AdminReference/auarf030.htm @@ -0,0 +1,57 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

SalvageLog

Purpose + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf031.htm b/doc/html/AdminReference/auarf031.htm new file mode 100644 index 0000000..26304b4 --- /dev/null +++ b/doc/html/AdminReference/auarf031.htm @@ -0,0 +1,59 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

TL_device_name +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf032.htm b/doc/html/AdminReference/auarf032.htm new file mode 100644 index 0000000..7fc27a1 --- /dev/null +++ b/doc/html/AdminReference/auarf032.htm @@ -0,0 +1,79 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

ThisCell (client version)

Purpose + + + + + +

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 +

fs getcellstatus +

fs setcell +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf033.htm b/doc/html/AdminReference/auarf033.htm new file mode 100644 index 0000000..38902a8 --- /dev/null +++ b/doc/html/AdminReference/auarf033.htm @@ -0,0 +1,61 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

ThisCell (server version)

Purpose + + + + + +

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 +

bos setcellname +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf034.htm b/doc/html/AdminReference/auarf034.htm new file mode 100644 index 0000000..c737918 --- /dev/null +++ b/doc/html/AdminReference/auarf034.htm @@ -0,0 +1,55 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

TE_device_name +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf035.htm b/doc/html/AdminReference/auarf035.htm new file mode 100644 index 0000000..3f7fcd2 --- /dev/null +++ b/doc/html/AdminReference/auarf035.htm @@ -0,0 +1,59 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

UserList

Purpose + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf036.htm b/doc/html/AdminReference/auarf036.htm new file mode 100644 index 0000000..2c207df --- /dev/null +++ b/doc/html/AdminReference/auarf036.htm @@ -0,0 +1,94 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

Vn

Purpose + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf037.htm b/doc/html/AdminReference/auarf037.htm new file mode 100644 index 0000000..db6d6d7 --- /dev/null +++ b/doc/html/AdminReference/auarf037.htm @@ -0,0 +1,46 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

Vvol_ID.vol

Purpose + + + + +

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 + + + + diff --git a/doc/html/AdminReference/auarf038.htm b/doc/html/AdminReference/auarf038.htm new file mode 100644 index 0000000..8f9a893 --- /dev/null +++ b/doc/html/AdminReference/auarf038.htm @@ -0,0 +1,75 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

VLLog

Purpose + + + +

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 +

vlserver +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf039.htm b/doc/html/AdminReference/auarf039.htm new file mode 100644 index 0000000..818a7b4 --- /dev/null +++ b/doc/html/AdminReference/auarf039.htm @@ -0,0 +1,57 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

VolserLog

Purpose + + + +

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 +

volserver +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf040.htm b/doc/html/AdminReference/auarf040.htm new file mode 100644 index 0000000..9ca5624 --- /dev/null +++ b/doc/html/AdminReference/auarf040.htm @@ -0,0 +1,56 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

VolumeItems

Purpose + + + + +

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 +

fs checkvolumes +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf041.htm b/doc/html/AdminReference/auarf041.htm new file mode 100644 index 0000000..ddfd57e --- /dev/null +++ b/doc/html/AdminReference/auarf041.htm @@ -0,0 +1,43 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

afszcm.cat

Purpose + + +

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 +

fstrace dump +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf042.htm b/doc/html/AdminReference/auarf042.htm new file mode 100644 index 0000000..e947816 --- /dev/null +++ b/doc/html/AdminReference/auarf042.htm @@ -0,0 +1,59 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bdb.DB0 and bdb.DBSYS1

Purpose + + + + + +

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 savedb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf043.htm b/doc/html/AdminReference/auarf043.htm new file mode 100644 index 0000000..db56a71 --- /dev/null +++ b/doc/html/AdminReference/auarf043.htm @@ -0,0 +1,79 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

fs getcacheparms +

fs setcachesize +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf044.htm b/doc/html/AdminReference/auarf044.htm new file mode 100644 index 0000000..64e4aba --- /dev/null +++ b/doc/html/AdminReference/auarf044.htm @@ -0,0 +1,82 @@ + + +Administration Reference + + + + + + + + + + + +

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 + + + + diff --git a/doc/html/AdminReference/auarf045.htm b/doc/html/AdminReference/auarf045.htm new file mode 100644 index 0000000..2087261 --- /dev/null +++ b/doc/html/AdminReference/auarf045.htm @@ -0,0 +1,60 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kaserver.DB0 and kaserver.DBSYS1

Purpose + + + + + +

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 +

kadb_check +

kas +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf046.htm b/doc/html/AdminReference/auarf046.htm new file mode 100644 index 0000000..bec1391 --- /dev/null +++ b/doc/html/AdminReference/auarf046.htm @@ -0,0 +1,55 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kaserverauxdb

Purpose + + +

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 +

kas unlock +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf047.htm b/doc/html/AdminReference/auarf047.htm new file mode 100644 index 0000000..8ffa0fb --- /dev/null +++ b/doc/html/AdminReference/auarf047.htm @@ -0,0 +1,60 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

prdb.DB0 and prdb.DBSYS1

Purpose + + + + + +

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 +

prdb_check +

pts +

ptserver +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf048.htm b/doc/html/AdminReference/auarf048.htm new file mode 100644 index 0000000..ca8ae53 --- /dev/null +++ b/doc/html/AdminReference/auarf048.htm @@ -0,0 +1,40 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf049.htm b/doc/html/AdminReference/auarf049.htm new file mode 100644 index 0000000..4be0431 --- /dev/null +++ b/doc/html/AdminReference/auarf049.htm @@ -0,0 +1,66 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

sysid

Purpose + + + + +

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. +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf050.htm b/doc/html/AdminReference/auarf050.htm new file mode 100644 index 0000000..46ee43c --- /dev/null +++ b/doc/html/AdminReference/auarf050.htm @@ -0,0 +1,165 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

tapeconfig

Purpose + + + +

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 + + + + diff --git a/doc/html/AdminReference/auarf051.htm b/doc/html/AdminReference/auarf051.htm new file mode 100644 index 0000000..e44f626 --- /dev/null +++ b/doc/html/AdminReference/auarf051.htm @@ -0,0 +1,58 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vldb.DB0 and vldb.DBSYS1

Purpose + + + + + + +

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 +

vldb_check +

vlserver +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf052.htm b/doc/html/AdminReference/auarf052.htm new file mode 100644 index 0000000..4db5a2c --- /dev/null +++ b/doc/html/AdminReference/auarf052.htm @@ -0,0 +1,116 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

afsmonitor Configuration File

Purpose + + +

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 +

fs host_name +

thresh fs | cm field_name thresh_val +[cmd_to_run] [arg₁] . . . +[arg_n] +

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 +

# 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 +

afsmonitor +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf053.htm b/doc/html/AdminReference/auarf053.htm new file mode 100644 index 0000000..6fe5ded --- /dev/null +++ b/doc/html/AdminReference/auarf053.htm @@ -0,0 +1,655 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

package Configuration File

Purpose + + + +

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. +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf054.htm b/doc/html/AdminReference/auarf054.htm new file mode 100644 index 0000000..eab3e26 --- /dev/null +++ b/doc/html/AdminReference/auarf054.htm @@ -0,0 +1,343 @@ + + +Administration Reference + + + + + + + + + + + +

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 bulk +

uss delete +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf055.htm b/doc/html/AdminReference/auarf055.htm new file mode 100644 index 0000000..6e7afaf --- /dev/null +++ b/doc/html/AdminReference/auarf055.htm @@ -0,0 +1,759 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

uss Template File

Purpose + + + +

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 +

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 +

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 +

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. +

mode_bits +

owner +

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 +

   /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 bulk +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf056.htm b/doc/html/AdminReference/auarf056.htm new file mode 100644 index 0000000..b2036c5 --- /dev/null +++ b/doc/html/AdminReference/auarf056.htm @@ -0,0 +1,26 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

AFS System Commands

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf057.htm b/doc/html/AdminReference/auarf057.htm new file mode 100644 index 0000000..3be407f --- /dev/null +++ b/doc/html/AdminReference/auarf057.htm @@ -0,0 +1,451 @@ + + +Administration Reference + + + + + + + + + + + +

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. +

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

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 commands have optional as well as required arguments; the command +descriptions and online help show optional arguments in square brackets ([ +]). +

Flags

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 +

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) +

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
+   
+

   % bos getdate fs1.abc.com ptserver kaserver
+   
+

   % 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. +

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 +

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). +

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]
+   
+

   
+   % 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 +

afsmonitor +

bos +

butc +

dlog +

dpass +

fms +

fs +

ftpd (AFS version) +

kadb_check +

kas +

kdb +

klog +

knfs +

pts +

runntp +

rxdebug +

scout +

sys +

translate_et +

up +

uss +

volinfo +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf058.htm b/doc/html/AdminReference/auarf058.htm new file mode 100644 index 0000000..4ccffb6 --- /dev/null +++ b/doc/html/AdminReference/auarf058.htm @@ -0,0 +1,433 @@ + + +Administration Reference + + + + + + + + + + + +

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 +(2¹⁶ is 64 KB) and 13 for a memory cache (2¹³ 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 (2¹⁴). +

   /usr/vice/etc/afsd -memcache -chunksize 14
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

afsmonitor Configuration File +

Vn +

cacheinfo + + + + + +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf059.htm b/doc/html/AdminReference/auarf059.htm new file mode 100644 index 0000000..9cc7d32 --- /dev/null +++ b/doc/html/AdminReference/auarf059.htm @@ -0,0 +1,329 @@ + + +Administration Reference + + + + + + + + + + + +

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 570 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 +

+ + +

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 +

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 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) +

The File Servers Screen +

The File Servers screen displays the values collected at the +most recent probe for File Server statistics. +

The first column always displays the hostnames of the machines running the +monitored File Servers. +

The Cache Managers Screen +

The Cache Managers screen displays the values collected at the +most recent probe for Cache Manager statistics. +

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 +

scout +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf060.htm b/doc/html/AdminReference/auarf060.htm new file mode 100644 index 0000000..5c59c78 --- /dev/null +++ b/doc/html/AdminReference/auarf060.htm @@ -0,0 +1,267 @@ + + +Administration Reference + + + + + + + + + + + +

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. +

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
+   
+

Privilege Required + + +

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 +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf061.htm b/doc/html/AdminReference/auarf061.htm new file mode 100644 index 0000000..1aaf9c8 --- /dev/null +++ b/doc/html/AdminReference/auarf061.htm @@ -0,0 +1,186 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf062.htm b/doc/html/AdminReference/auarf062.htm new file mode 100644 index 0000000..39ba174 --- /dev/null +++ b/doc/html/AdminReference/auarf062.htm @@ -0,0 +1,116 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

Related Information +

backup delhost +

backup listhosts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf063.htm b/doc/html/AdminReference/auarf063.htm new file mode 100644 index 0000000..c0de2f7 --- /dev/null +++ b/doc/html/AdminReference/auarf063.htm @@ -0,0 +1,189 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

-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 +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf064.htm b/doc/html/AdminReference/auarf064.htm new file mode 100644 index 0000000..b6bf0a9 --- /dev/null +++ b/doc/html/AdminReference/auarf064.htm @@ -0,0 +1,109 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf065.htm b/doc/html/AdminReference/auarf065.htm new file mode 100644 index 0000000..0d3d45e --- /dev/null +++ b/doc/html/AdminReference/auarf065.htm @@ -0,0 +1,73 @@ + + +Administration Reference + + + + + + + + + + + +

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 help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf066.htm b/doc/html/AdminReference/auarf066.htm new file mode 100644 index 0000000..94dea05 --- /dev/null +++ b/doc/html/AdminReference/auarf066.htm @@ -0,0 +1,124 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf067.htm b/doc/html/AdminReference/auarf067.htm new file mode 100644 index 0000000..735b58b --- /dev/null +++ b/doc/html/AdminReference/auarf067.htm @@ -0,0 +1,82 @@ + + +Administration Reference + + + + + + + + + + + +

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 +

Related Information +

backup adddump +

backup listdumps +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf068.htm b/doc/html/AdminReference/auarf068.htm new file mode 100644 index 0000000..2f91153 --- /dev/null +++ b/doc/html/AdminReference/auarf068.htm @@ -0,0 +1,183 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup deletedump

+ + + + + +

Purpose +

Deletes one or more dump records from the Backup Database +

Synopsis +

backup deletedump [-dumpid <dump id>⁺]  [-from <date time>⁺]  [-to <date time>⁺]
+                  [-localauth]  [-cell <cell name>]  [-help]
+  
+backup dele [-d <dump id>⁺]  [-f <date time>⁺]  [-t <date time>⁺]
+            [-l]  [-c <cell name>]  [-h]
+

Description +

The backup deletedump command deletes one or more dump records +from the Backup Database. Either use the -dumpid argument to +specify the dump ID number of one or more dumps, or use the -from +and -to arguments to delete the records for all regular dumps +created during the time period bracketed by the specified values. +

Use this command to remove dump records that are incorrect (possibly +because a dump operation was interrupted or failed), or that correspond to +dumps that are expired or otherwise no longer needed. +

Cautions +

The only way to remove the dump record for an appended dump is to remove +the record for its initial dump, and doing so removes the records for all of +the initial dump's associated appended dumps. +

The only way to remove the record for a Backup Database dump (created with +the backup savedb command) is to specify its dump ID number with +the -dumpid argument. Using the -from and +-to arguments never removes database dump records. +

Removing records of a dump makes it impossible to restore data from the +corresponding tapes or from any dump that refers to the deleted dump as its +parent, directly or indirectly. That is, restore operations must begin +with the full dump and continue with each incremental dump in order. If +the records for a specific dump are removed, it is not possible to restore +data from later incremental dumps unless the deleted records are restored by +running the backup scantape command with the -dbadd +flag. +

If a dump set contains any dumps that were created outside the time range +specified by the -from and -to arguments, the command +does not delete any of the records associated with the dump set, even if some +of them represent dumps created during the time range. +

Options +

-dumpid +

Specifies the dump ID of each dump record to delete. The +corresponding dumps must be initial dumps; it is not possible to delete +appended dump records directly, but only by deleting the record of their +associated initial dump. Using this argument is the only way to delete +records of Backup Database dumps (created with the backup savedb +command). +

Provide either this argument or the -to (and optionally +-from) argument. +

-from +

Specifies the beginning of a range of dates; the record for any dump +created during the indicated period of time is deleted. +

Omit this argument to indicate the default of midnight (00:00 hours) +on 1 January 1970 (UNIX time zero), or provide a date value in the format +mm/dd/yyyy [hh:MM]. The month (mm), +day (dd), and year (yyyy) are required. The hour and +minutes (hh:MM) are optional, but if provided must be +in 24-hour format (for example, the value 14:36 represents +2:36 p.m.). If omitted, the time defaults to +midnight (00:00 hours). +

The -to argument must be provided along with this one. +
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 +

Specifies the end of a range of dates; the record of any dump created +during the range is deleted from the Backup Database. +

Provide either the value NOW to indicate the current date and +time, or a date value in the same format as for the -from +argument. Valid values for the year (yyyy) 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 any later date to +the maximum value. +

If the time portion (hh:MM) is omitted, it defaults to 59 +seconds after midnight (00:00:59 hours). Similarly, the +backup command interpreter automatically adds 59 seconds to any +time value provided. In both cases, adding 59 seconds compensates for +how the Backup Database and backup dumpinfo command represent dump +creation times in hours and minutes only. For example, the Database +records a creation timestamp of 20:55 for any dump operation +that begins between 20:55:00 and 20:55:59. +Automatically adding 59 seconds to a time thus includes the records for all +dumps created during that minute. +

Provide either this argument, or the -dumpid argument. +This argument is required if the -from argument is provided. +

Caution: Specifying the value NOW for this +argument when the -from argument is omitted deletes all dump +records from the Backup Database (except for Backup Database dump records +created with the backup savedb command). +
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. +
+

-localauth +

-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 +

At the conclusion of processing, the output lists the dump IDs of all dump +records deleted in the following format: +

   The following dumps were deleted:
+        dump ID 1
+        dump ID 2
+        etc.
+   
+

Examples +

The following command deletes the dump record with dump ID 653777462, and +for any appended dumps associated with it: +

   % backup deletedump -dumpid 653777462
+   The following dumps were deleted:
+        653777462
+   
+

The following command deletes the Backup Database record of all dumps +created between midnight on 1 January 1997 and 23:59:59 hours on +31 December 1997: +

   % backup deletedump -from 01/01/1997 -to 12/31/1997
+   The following dumps were deleted:
+        598324045
+        598346873
+           ...
+           ...
+        653777523
+        653779648
+   
+

Privilege Required +

Related Information +

backup dumpinfo +

backup scantape +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf069.htm b/doc/html/AdminReference/auarf069.htm new file mode 100644 index 0000000..8f98cb4 --- /dev/null +++ b/doc/html/AdminReference/auarf069.htm @@ -0,0 +1,93 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup delhost

+ + + + + +

Purpose +

Deletes a Tape Coordinator entry from the Backup Database +

Synopsis +

backup delhost -tapehost <tape machine name> [-portoffset <TC port offset>]
+               [-localauth]  [-cell <cell name>]  [-help]
+   
+backup delh -t <tape machine name>  [-p <TC port offset>]
+            [-l]  [-c <cell name>]  [-h]
+

Description +

The backup delhost command deletes the indicated Tape +Coordinator entry from the Backup Database. It is then impossible to +submit backup operations to that Tape Coordinator, even if it is still +running. To keep configuration information consistent, also remove the +corresponding entry from the /usr/afs/backup/tapeconfig file on the +Tape Coordinator machine. +

To list the Tape Coordinator machines and port offsets defined in the +Backup Database, issue the backup listhosts command. +

Options +

-tapehost +: Specifies the hostname of the machine housing the Tape Coordinator to +delete. +
-portoffset +: Specifies the port offset number of the Tape Coordinator to delete. +If omitted, it defaults to 0. If provided, it is an integer +between 0 (zero) and 58510, and must match the port +offset number assigned to the same combination of Tape Coordinator and tape +device or file in the /usr/afs/backup/tapeconfig file on the Tape +Coordinator machine indicated 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 deletes the Backup Database entry for the Tape +Coordinator with port offset 2 on the Tape Coordinator machine +backup3.abc.com: +

   % backup delhost -tapehost backup3.abc.com -portoffset 2
+   
+

Privilege Required +

Related Information +

backup addhost +

backup listhosts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf070.htm b/doc/html/AdminReference/auarf070.htm new file mode 100644 index 0000000..4308ba8 --- /dev/null +++ b/doc/html/AdminReference/auarf070.htm @@ -0,0 +1,94 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup delvolentry

+ + + + + + +

Purpose +

Deletes a volume entry from a volume set +

Synopsis +

backup delvolentry -name <volume set name>  -entry <volume set index> 
+                   [-localauth]  [-cell <cell name>]  [-help]
+   
+backup delvole  -n <volume set name>  -e <volume set index>
+                [-l]  [-c <cell name>]  [-h]
+

Description +

The backup delvolentry command deletes the indicated volume +entry from the volume set specified with the -name argument. +Use the -entry argument to identify the volume entry by its index +number. To display the index numbers, use the backup +listvolsets command. +

If there are any remaining volume entries with index numbers higher than +the deleted entry, their indexes are automatically decremented to eliminate +any gaps in the indexing sequence. +

Cautions +

Deleting volume entries from a temporary volume set is possible only within +the interactive session in which the volume set was created. +

Options +

-name +: Names the volume set from which to delete a volume entry. +
-entry +: Specifies the index number of the volume entry to delete. Use the +backup listvolsets command to display the index numbers for a +volume set's volume entries. +
-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 fourth volume entry from the volume set +called sys: +

   % backup delvolentry -name sys -entry 4
+   
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf071.htm b/doc/html/AdminReference/auarf071.htm new file mode 100644 index 0000000..04a0651 --- /dev/null +++ b/doc/html/AdminReference/auarf071.htm @@ -0,0 +1,86 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup delvolset

+ + + + + +

Purpose +

Deletes one or more volume sets from the Backup Database +

Synopsis +

backup delvolset -name <volume set name>⁺
+                 [-localauth]  [-cell <cell name>]  [-help]
+   
+backup delvols -n <volume set name>⁺  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup delvolset command deletes each volume set named by +the -name argument, and the volume entries each contains, from the +Backup Database. The backup listvolsets command lists the +volume sets (and their volume entries) currently defined in the Backup +Database. +

Cautions +

Deleting a temporary volume set is possible only within the interactive +session in which it was created. Exiting the interactive session also +destroys the temporary volume set automatically. +

Options +

-name +: Names each volume set 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 volume set called user and all +volume entries in it: +

   % backup delvolset user
+   
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf072.htm b/doc/html/AdminReference/auarf072.htm new file mode 100644 index 0000000..56f8b69 --- /dev/null +++ b/doc/html/AdminReference/auarf072.htm @@ -0,0 +1,256 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup diskrestore

+ + + + + + +

Purpose +

Restores the entire contents of a partition +

Synopsis +

backup diskrestore -server <machine to restore> 
+                   -partition <partition to restore>
+                   [-portoffset <TC port offset>⁺]  
+                   [-newserver <destination machine>]
+                   [-newpartition <destination partition>]
+                   [-extension <new volume name extension>]
+                   [-n]  [-localauth]  [-cell <cell name>]  [-help]
+   
+backup di -s <machine to restore> -pa <partition to restore>
+          [-po <TC port offset>⁺]  [-news <destination machine>]
+          [-newp <destination partition>]  [-e <new volume name extension>]
+          [-n]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup diskrestore command restores all of the volumes for +which the Volume Location Database (VLDB) lists a read/write site on the +partition specified with the -server and -partition +arguments. It is useful if a disk or machine failure corrupts or +destroys the data on an entire partition. (To restore any read-only or +backup volumes that resided on the partition, use the vos release +and vos backup commands, respectively, after restoring the +read/write version.) +

If restoring only selected volumes to a single site, it is usually more +efficient to use the backup volrestore command. To restore +multiple volumes to many different sites, use the backup +volsetrestore command. +

(If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file on the Tape +Coordinator machine associated with the specified port offset, then the Backup +System restores data from the backup data file listed for that port offset in +the Tape Coordinator's /usr/afs/backup/tapeconfig file, +instead of from tape. For the sake of clarity, the following text +refers to tapes only, but the Backup System handles backup data files in much +the same way.) +

The Backup System determines whether the read/write or backup version of +each volume was dumped more recently, and restores the dumps of that version, +starting with the most recent full dump. It resets the creation +timestamp of each restored volume to the date and time at which it begins +restoring the volume (the creation timestamp appears in the +Creation field of the output from the vos examine and +vos listvol commands). +

If all of the full and incremental dumps of all relevant volumes were not +written on compatible tape devices, use the -portoffset argument to +list multiple port offset numbers in the order in which the tapes are needed +(first list the port offset for the full dump, second the port offset for the +level 1 incremental dump, and so on). This implies that the full dumps +of all relevant volumes must have been written to a type of tape that the +first Tape Coordinator can read, the level 1 incremental dumps to a type of +tape the second Tape Coordinator can read, and so on. If dumps are on +multiple incompatible tape types, use the backup volrestore command +to restore individual volumes, or the backup volsetrestore command +after defining groups of volumes that were dumped to compatible tape +types. For further discussion, see the IBM AFS Administration +Guide. +

By default, the Backup System restores the contents of the specified +partition to that same partition. To restore the contents to an +alternate site, combine the following options as indicated. The Backup +System removes each volume from the original site, if it still exists, and +records the change of site in the VLDB. +

To restore to a different partition on the same file server machine, +provide the -newpartition argument. +
To restore to the partition with the same name on a different file server +machine, provide the -newserver argument. +
To restore to a completely different site, combine the +-newserver and -newpartition arguments. +

To print out a list of the tapes containing the needed dumps, without +actually performing the restore operation, include the -n flag +along with the other options to be used on the actual command. +

The Tape Coordinator's default response to this command is to access +the first tape it needs by invoking the MOUNT instruction in the +local CFG_device_name file, or by prompting the backup +operator to insert the tape if there is no MOUNT +instruction. However, if the AUTOQUERY NO instruction +appears in the CFG_device_name file, or if the issuer of +the butc command included the -noautoquery flag, the +Tape Coordinator instead expects the tape to be in the device already. +If it is not, or is the wrong tape, the Tape Coordinator invokes the +MOUNT instruction or prompts the operator. It also invokes +the MOUNT instruction or prompts for any additional tapes needed to +complete the restore operation; the backup operator must arrange to +provide them. +

Cautions +

If issuing this command to recover data after a disk crash or other damage, +be sure not to issue the vos syncserv command first. Doing +so destroys the VLDB record of the volumes that resided on the +partition. +

Options +

-server +

Names the file server machine that the VLDB lists as the site of the +volumes that need to be restored. +

-partition +

Names the partition that the VLDB lists as the site of the volumes that +need to be restored. +

-portoffset +

Specifies one or more port offset numbers (up to a maximum of 128), each +corresponding to a Tape Coordinator to use in the operation. If there +is more than one value, the Backup System uses the first one when restoring +the full dump of each volume, the second one when restoring the level 1 +incremental dump of each volume, and so on. It uses the final value in +the list when restoring dumps at the corresponding depth in the dump hierarchy +and at all lower levels. +

Provide this argument unless the default value of 0 (zero) is appropriate +for all dumps. If 0 is just one of the values in the list, +provide it explicitly in the appropriate order. +

-newserver +

Names an alternate file server machine to which to restore the +volumes. If this argument is omitted, the volumes are restored to the +file server machine named by the -server argument. +

-newpartition +

Names an alternate partition to which to restore the data. If this +argument is omitted, the volumes are restored to the partition named by the +-partition argument. +

-extension +

Creates a new volume for each volume being restored, to house the restored +data. The Backup System derives the new volume's name by appending +the specified string to the read/write base name listed in the VLDB, and +creates a new VLDB volume entry. The Backup System preserves the +contents of the volumes on the partition, if any still exist. Any +string other than .readonly or .backup is +acceptable, but the combination of the base name and extension cannot exceed +22 characters in length. To use a period to separate the extension from +the name, specify it as the first character of the string (as in +.rst, for example). +

-n +

Displays a list of the tapes necessary to perform the requested restore, +without actually performing the operation. +

-localauth +

-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 +

If a tape error occurs during the restore operation, the Tape Coordinator +displays the following messages: +

   Restore operation on volume name failed due to tape error
+   Do you want to continue (y/n)?
+   
+

where name is the name of the volume that was being restored when +the tape error occurred. Enter the value y to continue the +operation without restoring the indicated volume or the value n to +terminate the operation. In the latter case, the operator can then +attempt to determine the cause of the tape error. +

If the issuer includes the -n flag with the command, the +following string appears at the head of the list of the tapes necessary to +perform the restore operation: +

   Tapes needed:
+   
+

Examples +

The following command restores the volumes for which the VLDB lists a +read/write site on the /vicepd partition of the machine +fs5.abc.com. The Tape Coordinator associated +with port offset 3 performs the operation. +

   % backup diskrestore -server fs5.abc.com -partition /vicepd -portoffset 3
+   
+

The following command restores the volumes for which the VLDB lists a +read/write site on the /vicepb partition of the machine +fs1.abc.com to a new site: the +/vicepa partition on the machine +fs3.abc.com. The Tape Coordinator associated +with port offset 0 performs the operation. (The command appears here on +two lines only for legibility.) +

   % backup diskrestore  -server fs1.abc.com -partition /vicepb   \
+                         -newserver fs3.abc.com -newpartition /vicepa
+   
+

The following command lists the tapes required to restore the volumes for +which the VLDB lists a read/write site on the /vicepm partition of +the machine fs4.abc.com: +

   % backup diskrestore -server fs4.abc.com -partition /vicepm -n
+   Tapes needed:
+   user.sunday1.1
+   user.sunday1.2
+   user.monday1.1
+   user.tuesday1.1
+   user.wednesday1.1
+   
+

Privilege Required +

Related Information +

backup dump +

backup volrestore +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf073.htm b/doc/html/AdminReference/auarf073.htm new file mode 100644 index 0000000..4711d5d --- /dev/null +++ b/doc/html/AdminReference/auarf073.htm @@ -0,0 +1,480 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup dump

+ + + + + + + + + + + + + + +

Purpose +

Creates a dump (dumps a volume set at a particular dump level) +

Synopsis +

backup dump [-volumeset <volume set name>]  [-dump <dump level name>]
+            [-portoffset <TC port offset>]  [-at <Date/time to start dump>⁺]
+            [-append]  [-n]  [-file <load file>]
+            [-localauth]  [-cell <cell name>]  [-help]
+  
+backup dump [-v <volume set name>]  [-d <dump level name>]
+            [-p <TC port offset>]  [-at <Date/time to start dump>⁺]
+            [-ap]  [-n]  [-f <load file>]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup dump command either dumps the volume set specified by +the -volumeset argument at the dump level specified by the +-dump argument and creates a Backup Database dump record about it, +or executes the dump instructions listed in the file named by the +-file argument. The Tape Coordinator indicated by the +-portoffset argument (or on each command in the file) executes the +operation. +

(If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file on the Tape +Coordinator machine associated with the specified port offset, then the Backup +System dumps data to the backup data file listed for that port offset in the +Tape Coordinator's /usr/afs/backup/tapeconfig file, rather +than to tape. For the sake of clarity, the following text refers to +tapes only, but the Backup System handles backup data files in much the same +way.) +

The term dumping refers to copying a collection of data to tape +or a backup data file, and the resulting collection is termed a +dump. The set of tapes that contain one or more dumps is +called a dump set. The first dump in a dump set is its +initial dump, and any dumps subsequently added to the dump set (by +use of the -append argument) are appended dumps. +Creating appended dumps is optional, and appended dumps can be of different +volume sets, and at different dump levels, than the initial dump. +

A full dump, created at a full dump level in the dump hierarchy, +contains all of the data that existed at the time of the dump in the volumes +belonging to the volume set. An incremental dump, created at +an incremental dump level, contains only data that has changed since the +volume set was dumped at the incremental level's parent dump +level (the dump level immediately above the incremental level in the +hierarchy), which can be a full or incremental level. More +specifically, an incremental dump includes only the files and directories that +have modification timestamps later than the clone date of the +volume included at the parent dump level. For backup and read-only +volumes, the clone date is the time at which the volume was cloned from its +read/write source before being included in the parent dump; for +read/write volumes, it represents the time at which the volume was locked for +inclusion in the parent dump. The clone date appears in the clone +date field of the output from the backup volinfo +command. As an example, an incremental dump at the +/full/week1/thursday level includes only files and directories that +have changed since the volume set was dumped at the /full/week1 +level. +

Initiating different types of dump operations +

To initiate a dump operation that is to start as soon as the relevant Tape +Coordinator is available, provide only the -volumeset, +-dump, -portoffset, and optionally -append +options. To schedule a single backup dump command to execute +in the future, also include the -at argument to specify the start +time. +

To append a dump to an existing dump set, include the -append +flag. The Backup System imposes the following conditions on appended +dumps: +

If writing to tape, the Tape Coordinator checks that it is the final one +in a dump set for which there are complete and valid tape and dump records in +the Backup Database. If not, it rejects the tape and requests an +acceptable one. The operator can use the -dbadd argument to +the backup scantape command to insert the necessary records into +the database. +
The most recent dump on the tape or in the backup data file must have +completed successfully. +
The dump set must begin with an initial dump that is recorded in the +Backup Database. If there are no dumps on the tape, then the Backup +System treats the dump operation as an initial dump and imposes the relevant +requirements (for example, checks the AFS tape name if appropriate). +

To schedule multiple dump operations, list the operations in the file named +by the -file argument. Optionally include the -at +argument to specify when the backup command interpreter reads the +file; otherwise it reads it immediately. Do not combine the +-file argument with the command's first three arguments or the +-append or -n flags. The commands in the file can +include any of the backup dump command's arguments, including +the -at argument to schedule them to run even later in the +future. +

To generate a list of the volumes included in a dump, without actually +dumping them, combine the -n flag with the options to be used on +the actual command. +

How the Backup System executes a dump operation +

Before beginning a dump operation, the Backup System verifies that there is +a Backup Database entry for the volume set, dump level, and port +offset. If the command is correctly formed and issued in interactive +mode, it is assigned a job number and added to the jobs list. List jobs +in interactive mode by using the (backup) jobs command; +terminate them with the (backup) kill command. +

After obtaining the list of volumes to dump from the Volume Location (VL) +Server, the Backup System sorts the list by site (server and +partition). It groups volumes from the same site together in the dump +to minimize the number of times the operator must change tapes during restore +operations. +

The dependence of an incremental dump on its parent means that a valid +parent dump must already exist for the Backup System to create its child +incremental dump. If the Backup System does not find a record of a dump +created at the immediate parent dump level, it looks in the Backup Database +for a dump created at one level higher in the hierarchy, and so on, up to the +full dump level if necessary. It creates an incremental dump at the +level one below the lowest valid parent dump set that it finds. If it +fails to find even a full dump, it dumps the volume set at the full dump +level. +

If the Backup System is unable to access a volume during a dump operation, +it skips the volume and dumps the remaining volumes from the volume +set. Possible reasons a volume is inaccessible include server machine +or process outages, or that the volume was moved between the time the Volume +Location (VL) Server generated the list of sites for the volume in the volume +set and the time the Backup System actually attempts to dump the data in +it. After the first dumping pass, the Backup System attempts to dump +each volume it skipped. If it still cannot dump a volume and the +ASK NO instruction does not appear in the +CFG_device_name file, it queries the operator as to +whether it needs to attempt to dump the volume again, omit the volume from the +dump, or halt the dump operation altogether. When prompted, the +operator can attempt to solve whatever problem prevented the Backup System +from accessing the volumes. If the ASK NO instruction +appears in the CFG_device_name file, the Backup System +omits the volume from the dump. +

Before scheduling a dump operation, the Backup System verifies that the +date specified by the -at argument is in the future, and checks the +validity of the volume set, dump level and port offset as for a regular dump +operation. It checks the validity of the parameters again just before +actually running the scheduled operation. +

Before writing an initial dump to a tape that does not have a permanent +name on the label, the Backup System checks that the AFS tape name on the +label is acceptable. If desired, disable name checking by including the +NAME_CHECK NO instruction in the +CFG_device_name file. +

If AFS tape name checking is enabled, the Backup System accepts the +following three types of values for the AFS tape name. If the name on +the label does not conform, the Backup System obtains a tape with an +acceptable label by invoking the MOUNT instruction in the +CFG_device_name file or prompting the operator. +

A name of the form +volume_set_name.dump_level_name.tape_index, where +volume_set_name matches the value of the -volumeset +argument, dump_level_name matches the last element in the pathname +value of the -dump argument, and tape_index reflects the +tape's place in a multitape dump set. As an example, the first +tape in a dump set for which the initial dump is of volume set user +at the dump level /sunday2/monday has AFS tape name +user.monday.1. If the label records this type +of AFS tape name, the Backup System retains the AFS tape name and writes the +dump to the tape. +
The string <NULL>, which usually indicates that a backup +operator has used the backup labeltape command to write a label on +the tape, but did not include the -name argument to assign an AFS +tape name. Presumably, the operator did include the -pname +argument to assign a permanent name. If the label records a +<NULL> value, the Backup System constructs and records on the +label the appropriate AFS tape name, and writes the dump on the tape. +
No value at all, because the tape has never been labeled or used in the +Backup System. As when the AFS tape name is <NULL>, the +Backup System constructs and records on the label the appropriate AFS tape +name, and writes the dump on the tape. +

To determine how much data it can write to a tape, the Tape Coordinator +reads the capacity recorded on the tape's label (placed there by +including the -size argument to the backup labeltape +command). If the label's capacity field is empty, the Tape +Coordinator uses the capacity recorded for the specified port offset in the +local tapeconfig file. If the capacity field in the +tapeconfig file is also empty, the Tape Coordinator uses the +maximum capacity of 2 TB. +

During a dump operation, the Tape Coordinator tracks how much data it has +written and stops shortly before it reaches what it believes is the +tape's capacity. If it is in the middle of writing the data for a +volume when it reaches that point, it writes a special marker that indicates +an interrupted volume and continues writing the volume on the next +tape. It can split a volume this way during both an initial and an +appended dump, and the fact that the volume resides on multiple tapes is +automatically recorded in the Backup Database. +

If the tape is actually larger than the expected capacity, then the Tape +Coordinator simply does not use the excess tape. If the tape is smaller +than the expected capacity, the Tape Coordinator can reach the end-of-tape +(EOT) unexpectedly while it is writing data. If the Tape Coordinator is +in the middle of the writing data from a volume, it obtains a new tape and +rewrites the entire contents of the interrupted volume to it. The data +from the volume that was written to the previous tape remains there, but is +never used. +

The Backup System allows recycling of tapes (writing a new dump set over an +old dump set that is no longer needed), but imposes the following +conditions: +

All dumps in the old dump set must be expired. The Backup System +always checks expiration dates, even when name checking is disabled. +
If the tape to be recycled does not have a permanent name and name +checking is enabled, then the AFS tape name derived from the new initial +dump's volume set name and dump level name must match the AFS tape name +already recorded on the label. +
The tape cannot already have data on it that belongs to the dump currently +being performed, because that implies that the operator or automated tape +device has not removed the previous tape from the drive, or has mistakenly +reinserted it. The Tape Coordinator generates the following message and +attempts to obtain another tape: +
```
   Can't overwrite tape containing the dump in progress
+   
+
```
+
The tape cannot contain data from a parent dump of the current +(incremental) dump, because overwriting a parent dump makes it impossible to +restore data from the current dump. The Tape Coordinator generates the +following message and attempts to obtain another tape: +
```
   Can't overwrite the parent dump parent_name (parent_dump_ID)
+   
+
```
+

To recycle a tape before all dumps on it have expired or if the AFS tape +name is wrong, use the backup labeltape command to overwrite the +tape's label and remove all associated tape and dump records from the +Backup Database. +

The Tape Coordinator's default response to this command is to access +the first tape by invoking the MOUNT instruction in the +CFG_device_name file, or by prompting the backup operator +to insert the tape if there is no MOUNT instruction. +However, if the AUTOQUERY NO instruction appears in the +CFG_device_name file, or if the issuer of the +butc command included the -noautoquery flag, the Tape +Coordinator instead expects the tape to be in the device already. If it +is not, the Tape Coordinator invokes the MOUNT instruction or +prompts the operator. It also invokes the MOUNT instruction +or prompts for any additional tapes needed to complete the dump +operation; the issuer must arrange to provide them. +

Cautions +

If a dump operation is interrupted or fails for any reason, data from all +volumes written to tape before the interrupt are valid can be used in a +restore operation. The Backup Database includes an entry for the failed +dump and for each volume that was successfully dumped. See the IBM +AFS Administration Guide for information on dealing with interrupted +dumps. +

If dumping to tape rather than a backup data file, it is best to use only +compatible tape devices (ones that can read the same type of tape). +Using compatible devices greatly simplifies restore operations. The +-portoffset argument to the backup diskrestore and +backup volsetrestore commands accepts multiple port offset numbers, +but the Backup System uses the first listed port offset when restoring all +full dumps, the second port offset when restoring all level 1 dumps, and so +on. At the very least, use compatible tape devices to perform dumps at +each level. If compatible tape devices are not used, the backup +volrestore command must be used to restore one volume at a time. +

Valid (unexpired) administrative tokens must be available to the +backup command interpreter both when it reads the file named by the +-file argument and when it runs each operation listed in the +file. Presumably, the issuer is scheduling dumps for times when no +human operator is present, and so must arrange for valid tokens to be +available on the local machine. One option is to issue all commands (or +run all scripts) on file server machines and use the -localauth +flag on the backup and vos commands. To protect +against improper access to the machine or the tokens, the machine must be +physically secure (perhaps even more protected than a Tape Coordinator machine +monitored by a human operator during operation). Also, if an unattended +dump requires multiple tapes, the operator must properly configure a tape +stacker or jukebox and the device configuration file. +

When the command is issued in regular (non-interactive) mode, the command +shell prompt does not return until the dump operation completes. To +avoid having to open additional connections, issue the command in interactive +mode, especially when including the -at argument to schedule dump +operations. +

Options +

-volumeset +

Names the volume set to dump. The -dump argument must be +provided along with this one; do not combine them with the +-file argument. If using a temporary volume set, the +vos dump command must be issued within the interactive session in +which the backup addvolset command was issued with the +-temporary flag. +

-dump +

Specifies the complete pathname of the dump level at which to dump the +volume set. The -volumeset argument must be provided along +with this one; do not combine them with the -file +argument. +

-portoffset +

Specifies the port offset number of the Tape Coordinator handling the +tapes for this operation. It must be provided unless the default value +of 0 (zero) is appropriate; do not combine it with the -file +argument. +

-at +

Specifies the date and time in the future at which to run the command, or +to read the file named by the -file argument. Provide a +value in the format mm/dd/yyyy [hh:MM], where the +month (mm), day (dd), and year (yyyy) are +required. 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 +Backup System automatically reduces any later date to the maximum +value. +

The hour and minutes (hh:MM) are optional, but if provided +must be in 24-hour format (for example, the value 14:36 +represents 2:36 p.m.). If omitted, the time +defaults to midnight (00:00 hours). +

-append +

Appends the dump onto the end of a tape that already contains data from +another dump. However, if the tape is not in fact part of an existing +dump set, the Backup System creates a new dump set using the parameters of +this dump. If the tape is not the last tape in the dump set, the Tape +Coordinator prompts for insertion of the appropriate tape. Do not +combine this argument with the -file argument. +

-n +

Displays the names of volumes to be included in the indicated dump, +without actually performing the dump operation. Do not combine this +argument with the -file argument. +

-file +

Place each backup dump command on its own line in the indicated +file, using the same syntax as for the command line, but without the word +backup at the start of the line. Each command must include a +value for the -volumeset and -dump arguments, and for +the -portoffset argument unless the default value of 0 is +appropriate. Commands in the file can also include any of the +backup dump command's optional options. In the +following example file, the first command runs as soon as the Backup System +reads the file, whereas the other commands are themselves scheduled; the +specified date and time must be later than the date and time at which the +Backup System reads the file. +

   dump user /sunday1/wednesday -port 1 
+   dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999
+   dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append
+   
+

Do not combine this argument with the -volumeset, +-dump, -portoffset, -append, or -n +options. +

-localauth +

-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 interpreter first generates a list of the volumes to be +included in the dump by matching the entries in the volume set against the +volumes listed in the Volume Location Database (VLDB). It prints the +list following the header: +

   Preparing to dump the following volumes:
+   
+

The following message then indicates that the command interpreter has +passed the dump request to the appropriate Tape Coordinator for +processing: +

   Starting dump.
+   
+

If the issuer includes the -n flag, the output is of the +following form: +

   Starting dump of volume set 'volume set' (dump set 'dump level')
+   Total number of volumes : number dumped
+   Would have dumped the following volumes:
+   list_of_volumes
+   
+

where list_of_volumes identifies each volume by name and volume ID +number. +

If the Tape Coordinator is unable to access a volume, it prints an error +message in its window and records the error in its log and error files. +

Examples +

The following command dumps the volumes in the volume set called +user at the dump level /full/sunday2/monday. The +issuer places the necessary tapes in the device with port offset 5. +

   % backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5
+   Preparing to dump the following volumes:
+   user.jones.backup   387623900
+   user.pat.backup     486219245
+   user.smith.backup   597315841
+          .                .
+          .                .
+   Starting dump.
+   
+

The following command displays the list of volumes to be dumped when the +user dumps the sys_sun volume set at the /full dump +level. +

   % backup dump -volumeset sys_sun -dump /full -n
+   Starting dump of volume set 'sys_sun' (dump set '/full')
+   Total number of volumes: 24
+   Would have dumped the following volumes:
+   sun4x_56      124857238
+   sun4x_56.bin  124857241
+       .            .
+       .            .
+   sun4x_55      124857997
+       .            .
+       .            .
+   
+

The following command schedules a dump of the volumes in the volume set +user at the dump level /sunday2/monday1 for 11:00 +p.m. on 14 June 1999. The appropriate Tape Coordinator +has port offset 0 (zero), so that argument is omitted. +

   % backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00
+   
+

Privilege Required +

Related Information +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf074.htm b/doc/html/AdminReference/auarf074.htm new file mode 100644 index 0000000..0af90a5 --- /dev/null +++ b/doc/html/AdminReference/auarf074.htm @@ -0,0 +1,340 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup dumpinfo

+ + + + + + + + +

Purpose +

Displays a dump record from the Backup Database +

Synopsis +

backup dumpinfo [-ndumps <no. of dumps>]  [-id <dump id>]
+                [-verbose]  [-localauth]  [-cell <cell name>]  [-help ]
+   
+backup dumpi [-n <no. of dumps>]  [-i <dump id>]
+             [-v]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup dumpinfo command formats and displays the Backup +Database record for the specified dumps. To specify how many of the +most recent dumps to display, starting with the newest one and going back in +time, use the -ndumps argument. To display more detailed +information about a single dump, use the -id argument. To +display the records for the 10 most recent dumps, omit both the +-ndumps and -id arguments. +

The -verbose flag produces very detailed information that is +useful mostly for debugging purposes. It can be combined only with the +-id argument. +

Options +

-ndumps +: Displays the Backup Database record for each of the specified number of +dumps that were most recently performed. If the database contains fewer +dumps than are requested, the output includes the records for all existing +dumps. Do not combine this argument with the -id or +-verbose options; omit all options to display the records for +the last 10 dumps. +
-id +: Specifies the dump ID number of a single dump for which to display the +Backup Database record. Precede the dump id value with the +-id switch; otherwise, the command interpreter interprets it +as the value of the -ndumps argument. Combine this argument +with the -verbose flag, but not with the -ndumps +argument; omit all options to display the records for the last 10 +dumps. +
-verbose +: Provides more detailed information about the dump specified with the +-id argument, which must be provided along with it. Do not +combine this flag with the -ndumps 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. +

Output +

If the -ndumps argument is provided, the output presents the +following information in table form, with a separate line for each dump: +

dumpid +

The dump ID number. +

parentid +

The dump ID number of the dump's parent dump. A value of +0 (zero) identifies a full dump. +

lv +

created +

The date and time at which the Backup System started the dump operation +that created the dump. +

nt +

nvols +

dump name +

The dump name in the form +

   volume_set_name.dump_level_name (initial_dump_ID)
+   
+

where volume_set_name is the name of the volume set, and +dump_level_name is the last element in the dump level pathname at +which the volume set was dumped. +

If the -id argument is provided alone, the first line of output +begins with the string Dump and reports information for the entire +dump in the following fields: +

id +: The dump ID number. +
level +: The depth in the dump hierarchy of the dump level used to create the +dump. A value of 0 (zero) identifies a full dump. A +value of 1 (one) or greater indicates an incremental dump made at +the specified level in the dump hierarchy. +
volumes +: The number of volumes for which the dump includes data. +
created +: The date and time at which the dump operation began. +

If an XBSA server was the backup medium for the dump (rather than a tape +device or backup data file), the following line appears next: +

   Backup Service: XBSA_program: Server: hostname
+

where XBSA_program is the name of the XBSA-compliant program and +hostname is the name of the machine on which the program runs. +

name +: The tape's permanent name if it has one, or its AFS tape name +otherwise, and its tape ID number in parentheses. +
nVolumes +: The number of volumes for which this tape includes dump data. +
created +: The date and time at which the Tape Coordinator began writing data to this +tape. +

Pos +: The relative position of each volume in this tape or file. On a +tape, the counter begins at position 2 (the tape label occupies position 1), +and increments by one for each volume. For volumes in a backup data +file, the position numbers start with 1 and do not usually increment only by +one, because each is the ordinal of the 16 KB offset in the file at which the +volume's data begins. The difference between the position numbers +therefore indicates how many 16 KB blocks each volume's data +occupies. For example, if the second volume is at position 5 and the +third volume in the list is at position 9, that means that the dump of the +second volume occupies 64 KB (four 16-KB blocks) of space in the file. +
Clone time +: For a backup or read-only volume, the time at which it was cloned from its +read/write source. For a Read/Write volume, it is the same as the dump +creation date reported on the first line of the output. +
Nbytes +: The number of bytes of data in the dump of the volume. +
Volume +: The volume name, complete with .backup or +.readonly extension if appropriate. +

If both the -id and -verbose options are provided, +the output is divided into several sections: +

The first section, headed by the underlined string Dump, +includes information about the entire dump. The fields labeled +id, level, created, and nVolumes +report the same values (though in a different order) as appear on the first +line of output when the -id argument is provided by itself. +Other fields of potential interest to the backup operator are: +
+
Group id +
The dump's group ID number, which is recorded in the +dump's Backup Database record if the GROUPID instruction +appears in the Tape Coordinator's +/usr/afs/backup/CFG_tcid file when the dump is created. +
maxTapes +
The number of tapes that contain the dump set to which this dump +belongs. +
Start Tape Seq +
The ordinal of the tape on which this dump begins in the set of tapes that +contain the dump set. +
+
For each tape that contains data from this dump, there follows a section +headed by the underlined string Tape. The fields labeled +name, written, and nVolumes report the same +values (though in a different order) as appear on the second and third lines +of output when the -id argument is provided by itself. Other +fields of potential interest to the backup operator are: +
+
expires +
The date and time when this tape can be recycled, because all dumps it +contains have expired. +
nMBytes Data and nBytes Data +
Summed together, these fields represent the total amount of dumped data +actually from volumes (as opposed to labels, filemarks, and other +markers). +
KBytes Tape Used +
The number of kilobytes of tape (or disk space, for a backup data file) +used to store the dump data. It is generally larger than the sum of the +values in the nMBytes Data and nBytes Data fields, +because it includes the space required for the label, file marks and other +markers, and because the Backup System writes data at 16 KB offsets, even if +the data in a given block doesn't fill the entire 16 KB. +
+
For each volume on a given tape, there follows a section headed by the +underlined string Volume. The fields labeled +name, position, clone, and nBytes +report the same values (though in a different order) as appear in the table +that lists the volumes in each tape when the -id argument is +provided by itself. Other fields of potential interest to the backup +operator are: +
+
id +
The volume ID. +
tape +
The name of the tape containing this volume data. +
+

Examples +

The following example displays information about the last five dumps: +

   % backup dumpinfo -ndumps 5
+      dumpid   parentid lv created          nt nvols dump name
+   924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
+   924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
+   924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
+   924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
+   925033000          0 0  04/25/1999 05:36  2    73 sys.week
+   
+

The following example displays a more detailed record for a single +dump. +

   % backup dumpinfo -id 922097346
+   Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
+   Tape: name monday.user.backup (922097346)
+   nVolumes 1, created 03/22/1999 05:09
+    Pos       Clone time   Nbytes Volume
+      1 03/22/1999 04:43 27787914 user.pat.backup
+   
+

The following example displays even more detailed information about the +dump displayed in the previous example (dump ID 922097346). This +example includes only one exemplar of each type of section (Dump, +Tape, and Volume): +

   % backup dumpinfo -id 922097346 -verbose
+   Dump
+   ----
+   id = 922097346
+   Initial id = 0
+   Appended id = 922099568
+   parent = 0
+   level = 0
+   flags = 0x0
+   volumeSet = user
+   dump path = /monday1
+   name = user.monday1
+   created = Mon Mar 22 05:09:06 1999
+   nVolumes = 1
+   id  = 0
+   tapeServer =
+   format= user.monday1.%d
+   maxTapes = 1
+   Start Tape Seq = 1
+   name = pat
+   instance =
+   cell =
+   Tape
+   ----
+   tape name = monday.user.backup
+   AFS tape name = user.monday1.1
+   flags = 0x20
+   written = Mon Mar 22 05:09:06 1999
+   expires = NEVER
+   kBytes Tape Used = 121
+   nMBytes Data = 0
+   nBytes  Data = 19092
+   nFiles = 0
+   nVolumes = 1
+   seq = 1
+   tapeid = 0
+   useCount = 1
+   dump = 922097346
+   Volume
+   ------
+   name = user.pat.backup
+   flags = 0x18
+   id = 536871640
+   server =
+   partition = 0
+   nFrags = 1
+   position = 2
+   clone = Mon Mar 22 04:43:06 1999
+   startByte = 0
+   nBytes = 19092
+   seq = 0
+   dump = 922097346
+   tape = user.monday1.1
+   
+

Privilege Required +

Related Information +

backup deletedump +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf075.htm b/doc/html/AdminReference/auarf075.htm new file mode 100644 index 0000000..0c75938 --- /dev/null +++ b/doc/html/AdminReference/auarf075.htm @@ -0,0 +1,86 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup help

+ + + +

Purpose +

Displays the syntax of specified backup commands or lists +functional descriptions of all backup commands +

Synopsis +

backup help  [-topic <help string>⁺]  [-help]
+  
+backup h [-t <help string>⁺]  [-h]
+

Description +

The backup help command displays the complete online help entry +(short description and syntax statement) for each operation code specified by +the -topic argument. If the -topic argument is +omitted, the output includes the first line (name and short description) of +the online help entry for every backup command. +

To list every backup command whose name or short description +includes a specified keyword, use the backup apropos +command. +

Options +

-topic +: Indicates each command for which to display the complete online help +entry. Omit the backup part of the command name, providing +only the operation code (for example, specify dump, not backup +dump). If this argument is omitted, the output briefly describes +every backup command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each backup command consists of the +following two or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following example displays the online help entry for the backup +dump command: +

   % backup help dump
+   backup dump: start dump
+   Usage: backup dump -volumeset <volume set name> -dump <dump level name> 
+   [-portoffset <TC port offset>]  [-at <Date/time to start dump>+] 
+   [-append]  [-n]  [-file <load file>]  [-help]
+   
+

Privilege Required +

None +

Related Information +

backup apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf076.htm b/doc/html/AdminReference/auarf076.htm new file mode 100644 index 0000000..bbd9168 --- /dev/null +++ b/doc/html/AdminReference/auarf076.htm @@ -0,0 +1,109 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup interactive

+ + + + + +

Purpose +

Enters interactive mode +

Synopsis +

backup [interactive]  [-localauth]  [-cell <cell name>]  [-help]
+  
+backup [i]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup interactive initiates an interactive session for +issuing backup commands. As indicated in the syntax +statement, the operation code (interactive) is optional. +

Several features of interactive mode distinguish it from regular +mode: +

In interactive mode, the backup> prompt replaces the system +(shell) prompt. The operator enters only a command's operation +code (omitting the command suite name, backup). +
If the -localauth flag or the -cell argument is +included on the backup (interactive) command, the settings apply to +all commands issued during that interactive session. The issuer does +not need to type them on every command. Another consequence is that the +flag and argument do not appear in the syntax statement generated by the +help subcommand or -help flag on an individual command +issued at the backup> prompt. +
The (backup) jobs and (backup) kill commands are +available only in interactive mode. It is not possible to track and +terminate backup operations as cleanly in non-interactive mode. +
It is not necessary to enclose strings that include metacharacters in +double quotes or other delimiters. +
The backup command interpreter establishes a connection to the +Backup Server, Volume Server and Volume Location (VL) Server processes as it +enters interactive mode, and uses the same connection for all commands during +the session. Execution time can therefore be faster than in +non-interactive mode, in which the command interpreter must establish a new +connection for each command. +

To exit an interactive session, issue the (backup) quit +command. +

Options +

-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 example shows how the -localauth flag and +-cell argument do not appear when the help dump +subcommand is issued in interactive mode. +

   % backup
+   backup> help dump
+   dump: start dump 
+   Usage: dump [-volumeset <volume set name>] [-dump <dump level name>] 
+   [-portoffset <TC port offset>] [-at <Date/time to start dump>+]
+   [-append ] [-n ] [-file <load file>] [-help ] 
+   
+

Privilege Required +

None. However, backup commands that require privilege in +regular mode still require it in interactive mode. +

Related Information +

backup jobs +

backup kill +

backup quit +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf077.htm b/doc/html/AdminReference/auarf077.htm new file mode 100644 index 0000000..2c95ab0 --- /dev/null +++ b/doc/html/AdminReference/auarf077.htm @@ -0,0 +1,176 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup jobs

+ + + + + + + +

Purpose +

Lists pending and running operations in interactive mode +

Synopsis +

jobs  [-help]
+  
+j [-h]
+

Description +

The (backup) jobs command lists the job ID number and status of +each backup operation running or pending in the current interactive +session. +

This command can be issued in interactive mode only. If the issuer +of the backup (interactive) command included the +-localauth flag, the -cell argument, or both, those +settings apply to this command also. +

To terminate operations that appear in the output, issue the (backup) +kill command and identify the operation to cancel with the job ID number +from this command's output. +

To check the status of a Tape Coordinator, rather than of a certain +operation, use the backup status command. +

Options +

-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output always includes the expiration date and time of the tokens that +the backup command interpreter is using during the current +interactive session, in the following format: +

   date   time: TOKEN EXPIRATION
+

If the issuer of the backup command included the +-localauth flag when entering interactive mode, the line instead +reads as follows: +

   :  TOKEN NEVER EXPIRES
+

The entry for a scheduled dump operation has the following format: +

   Job job_ID:  timestamp:  dump  volume_set  dump_level
+

where +

job_ID +: Is a job identification number assigned by the Backup System. +
timestamp +: Indicates the date and time the dump operation is to begin, in the format +month/date/year +hours:minutes (in 24-hour format) +
volume_set +: Indicates the volume set to dump. +
dump_level +: Indicates the dump level at which to perform the dump operation. +

The line for a pending or running operation of any other type has the +following format: +

   Job job_ID:  operation  status
+

where +

job_ID +

Is a job identification number assigned by the Backup System. +

operation +

Identifies the operation the Tape Coordinator is performing, which is +initiated by the indicated command: +

Dump (dump name) +

Initiated by the backup dump command. The dump +name has the following format: +

volume_set_name.dump_level_name +

Restore +

Initiated by the backup diskrestore, backup +volrestore, or backup volsetrestore command. +

Labeltape (tape_label) +

Initiated by the backup labeltape command. The +tape_label is the name specified by the backup labeltape +command's -name or -pname argument. +

Scantape +

Initiated by the backup scantape command. +

SaveDb +

Initiated by the backup savedb command. +

RestoreDb +

Initiated by the backup restoredb command. +

status +

Indicates the job's current status in one of the following +messages. If no message appears, the job is either still pending or has +finished. +

number Kbytes, volume volume_name +: For a running dump operation, indicates the number of kilobytes copied to +tape or a backup data file so far, and the volume currently being +dumped. +
number Kbytes, restore.volume +: For a running restore operation, indicates the number of kilobytes copied +into AFS from a tape or a backup data file so far. +
[abort requested] +: The (backup) kill command was issued, but the termination +signal has yet to reach the Tape Coordinator. +
[abort sent] +: The operation is canceled by the (backup) kill command. +Once the Backup System removes an operation from the queue or stops it from +running, it no longer appears at all in the output from the command. +
[butc contact lost] +: The backup command interpreter cannot reach the Tape +Coordinator. The message can mean either that the Tape Coordinator +handling the operation was terminated or failed while the operation was +running, or that the connection to the Tape Coordinator timed out. +
[done] +: The Tape Coordinator has finished the operation. +
[drive wait] +: The operation is waiting for the specified tape drive to become +free. +
[operator wait] +: The Tape Coordinator is waiting for the backup operator to insert a tape +in the drive. +

Examples +

The following example shows that two restore operations and one dump +operation are running (presumably on different Tape Coordinators) and that the +backup command interpreter's tokens expire on 22 April 1999 at +10:45 am: +

   backup> jobs
+   Job 1: Restore, 1306 Kbytes, restore.volume
+   Job 2: Dump (user.sunday1), 34 Kbytes, volume user.pat.backup
+   Job 3: Restore, 2498 Kbytes, restore.volume
+          04/22/1999 10:45: TOKEN EXPIRATION
+   
+

Privilege Required +

None. However, queuing any operation requires privilege, and it is +possible to issue this command only within the interactive session in which +the jobs are queued. +

Related Information +

backup interactive +

backup kill +

backup quit +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf078.htm b/doc/html/AdminReference/auarf078.htm new file mode 100644 index 0000000..2e20bf6 --- /dev/null +++ b/doc/html/AdminReference/auarf078.htm @@ -0,0 +1,139 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup kill

+ + + + + + +

Purpose +

Terminates a pending or running operation +

Synopsis +

kill -id <job ID or dump set name> [-help]
+  
+k -i <job ID or dump set name>  [-h]
+

Description +

The (backup) kill command dequeues a Backup System operation +that is pending, or terminates an operation that is running, in the current +interactive session. It is available only in interactive mode. +If the issuer of the backup (interactive) command included the +-localauth flag, the -cell argument, or both, then those +settings apply to this command also. +

To terminate a dump operation, specify either the dump name +(volume_set_name.dump_level_name) or its job ID +number, which appears in the output from the (backup) jobs +command. To terminate any other type of operation, provide the job ID +number. +

The effect of terminating an operation depends on the type and current +state of the operation: +

If an operation is still pending, the Tape Coordinator removes it from the +queue with no other lasting effects. +
If the Tape Coordinator is unable to process the termination signal before +an operation completes, it simply confirms the operation's +completion. The operator must take the action necessary to undo the +effects of the incorrect operation. +
If a tape labeling operation is running, the effect depends on when the +Tape Coordinator receives the termination signal. The labeling +operation is atomic, so it either completes or does not begin at all. +Use the backup readlabel command to determine if the labeling +operation completed, and reissue the backup labeltape command to +overwrite the incorrect label if necessary. +
If a tape scanning operation is running, it terminates with no other +effects unless the -dbadd flag was included on the +backup command. In that case, the Backup System possibly has +already written new Backup Database records to represent dumps on the scanned +tape. If planning to restart the scanning operation, first locate and +remove the records created during the terminated operation: a repeated +backup scantape operation exits automatically when it finds that a +record that it needs to create already exists. +
If a dump operation is running, all of the volumes written to the tape or +backup data file before the termination signal is received are complete and +usable. If the operation is restarted, the Backup System performs all +the dumps again from scratch, and assigns a new dump ID number. If +writing the new dumps to the same tape or file, the operator must relabel it +first if the interrupted dump is not expired. If writing the new dump +to a different tape or file, the operator can remove the dump record +associated with the interrupted dump to free up space in the database. +
If a restore operation is running, completely restored volumes are online +and usable. However, it is unlikely that many volumes are completely +restored, given that complete restoration usually requires data from multiple +tapes. If the termination signal comes before the Backup System has +accessed all of the necessary tapes, each volume is only partially written and +is never brought online. It is best to restart the restore operation +from scratch to avoid possible inconsistencies. See also the +Cautions section. +

Cautions +

It is best not to issue the (backup) kill command against +restore operations. If the termination signal interrupts a restore +operation as the Backup System is overwriting an existing volume, it is +possible to lose the volume entirely (that is, to lose both the contents of +the volume as it was before the restore and any data that was restored before +the termination signal arrived). The data being restored still exists +on the tape, but some data can be lost permanently. +

Options +

-id +

Identifies the backup operation to terminate. Provide one of two +types of values: +

The operation's job ID number, as displayed in the output of the +(backup) jobs command. +
For a dump operation, either the job ID number or a dump name of the form +volume_set_name.dump_level_name, where +volume_set_name is the name of the volume set being dumped and +dump_level_name is the last element in the dump level pathname at +which the volume set is being dumped. The dump name appears in the +output of the (backup) jobs command along with the job ID +number. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command terminates the operation with job ID 5: +

   backup> kill 5
+   
+

The following command terminates the dump operation called +user.sunday1: +

   backup> kill user.sunday1
+   
+

Privilege Required +

The issuer must have the privilege required to initiate the operation being +cancelled. Because this command can be issued only within the +interactive session during which the operation was initiated, the required +privilege is essentially guaranteed. +

Related Information +

backup interactive +

backup jobs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf079.htm b/doc/html/AdminReference/auarf079.htm new file mode 100644 index 0000000..3b532ad --- /dev/null +++ b/doc/html/AdminReference/auarf079.htm @@ -0,0 +1,224 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup labeltape

+ + + + + + + + + + + + +

Purpose +

Creates the magnetic label on a tape +

Synopsis +

backup labeltape [-name <AFS tape name, defaults to NULL>]
+                 [-size <tape size in Kbytes, defaults to size in tapeconfig>]
+                 [-portoffset <TC port offset>] 
+                 [-pname <permanent tape name>] 
+                 [-localauth]  [-cell <cell name>]  [-help]
+   
+backup la [-n <AFS tape name, defaults to NULL>]
+          [-s <tape size in Kbytes, defaults to size in tapeconfig>]
+          [-po <TC port offset>]  [-pn <permanent tape name>]
+          [-l]  [-c <cell name>]  [-h]
+

Description +

The backup labeltape command creates a magnetic label, readable +by the Backup System, at the beginning of a tape. The label records the +tape's name (either a permanent name, or an AFS tape +name that reflects the tape's contents in a prescribed format) and +its capacity. +

(If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file on the Tape +Coordinator machine associated with the specified port offset, then the +backup command writes label information to the first 16 KB block in +the backup data file listed for that port offset in the Tape +Coordinator's /usr/afs/backup/tapeconfig file, rather than at +the beginning of a tape. For the sake of clarity, the following text +refers to tapes only, but the Backup System handles backup data files in much +the same way.) +

Relabeling a tape that already contains AFS backup data effectively makes +the data unusable, because the command removes the Backup Database record of +the complete dump set of which the tape is a part. Use this command to +enable recycling of a tape that contains unexpired dumps that are not actually +still needed. +

To write a permanent name on the label, include the -pname +argument to specify a string of up to 32 characters. The permanent name +persists until the -pname argument is again included on the +backup labeltape command, regardless of the tape's contents +and of how often the tape is otherwise relabeled or recycled. Include +this argument or the -name argument, but not both. If this +argument is included, the AFS tape name is set to <NULL>. +The permanent name is set to <NULL> if this argument is omitted +and no permanent name already exists. +

The issuer must ensure that a permanent name is unique among the tapes used +for AFS backup in the cell, because the backup command interpreter +does not verify that another tape does not already have the same permanent +name. When a tape has a permanent name, the Backup System uses it +instead of the AFS tape name in most prompts and when referring to the tape in +output from backup commands. The permanent name appears in +the tape name field of the output from the backup +readlabel command. +

To write an AFS tape name on the label, provide a value for the +-name argument in the required format described in the +Options section. Include the -name argument or +the -pname argument, but not both. If this argument is +omitted, the AFS tape name is set to <NULL>, but the Backup +System automatically assigns the appropriate name when the tape is used in a +future backup dump or backup savedb operation. +The AFS tape name appears in the AFS tape +name field of the output from the backup readlabel and +backup scantape commands. +

The backup command interpreter does not accept the +-name argument if the tape already has a permanent name. To +erase a tape's permanent name, provide a null value to the +-pname argument by issuing the following command: +

   % backup labeltape -pname ""
+   
+

To record the tape's capacity on the label, specify a number of +kilobytes as the -size argument. If the argument is omitted +the first time a tape is labeled, the Backup System records the default tape +capacity recorded for the specified port offset in the +/usr/afs/backup/tapeconfig file on the Tape Coordinator +machine. Subsequently, the value in the size field persists until the +-size argument is again included on the backup labeltape +command. +

To determine how much data can be written to a tape during a backup +dump or backup savedb operation, the Tape Coordinator reads +the capacity recorded on the tape's label (or uses the value associated +with its port offset in the /usr/afs/backup/tapeconfig file, if the +tape was never labeled). For further description, see the backup +dump reference page. +

The Tape Coordinator's default response to this command is to access +the tape by invoking the MOUNT instruction in the local +/usr/afs/backup/CFG_device_name file, or by prompting the +backup operator to insert the tape if there is no MOUNT +instruction. However, if the AUTOQUERY NO instruction +appears in the CFG_device_name file, or if the issuer of +the butc command included the -noautoquery flag, the +Tape Coordinator instead expects the tape to be in the device already. +If it is not, the Tape Coordinator invokes the MOUNT instruction or +prompts the operator. +

Options +

-name +

Specifies the AFS tape name to record on the label. Include this +argument or the -pname argument, but not both. If this +argument is omitted, the AFS tape name is set to <NULL>. +If this argument is provided, it must have the following format: +

   volume_set_name.dump_level_name.tape_index
+   
+

for the tape to be acceptable for use in a future backup dump +operation. The volume_set_name must match the volume set name +of the initial dump to be written to the tape, dump_level_name must +match the last element of the dump level pathname at which the volume set will +be dumped, and tape_index indicates the order of the tape in the dump +set (indexing begins with 1). To disable this type of name +checking, include the NAME_CHECK NO instruction in the +CFG_device_name file. +

For the tape to be acceptable for use in a future backup savedb +operation, the value specified for the -name argument must have the +following format: +

   Ubik_db_dump.tape_index
+   
+

where tape_index indicates the order of the tape in the set of +tapes that house the Backup Database dump; indexing begins with 1 +(one). +

-size +

Specifies the tape capacity to record on the label. Provide an +integer value followed by a letter that indicates units, with no intervening +space. A unit value of k or K indicates +kilobytes, m or M indicates megabytes, and g +or G indicates gigabytes. If the units letter is omitted, +the default is kilobytes. +

If this argument is omitted the first time a tape is labeled, the Backup +System records the capacity that is associated with the specified port offset +in the /usr/afs/backup/tapeconfig file on the Tape Coordinator +machine. The value recorded the first time then persists until the +-size argument is provided on a future issuance of the +command. +

-portoffset +

Specifies the port offset number of the Tape Coordinator handling the tape +for this operation. +

-pname +

Specifies the permanent name to record on the label. It can be up +to 32 characters in length, and include any alphanumeric characters. +Avoid metacharacters that have a special meaning to the shell, to avoid having +to mark them as literal in commands issued at the shell prompt. +

Include this argument or the -name argument, but not +both. If this argument is provided, the AFS tape name is set to +<NULL>. If this argument is omitted, any existing +permanent name is retained. +

-localauth +

-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 records the AFS tape name +user.monthly.1 on the label of the tape in the device +with port offset 3: +

   % backup labeltape -name user.monthly.1 -portoffset 3
+   
+

The following three commands are equivalent in effect: they all +record a capacity of 2 GB on the label of the tape in the device with port +offset 4. They set the AFS tape name to <NULL> and leave +the permanent name unchanged. +

   % backup labeltape -size 2g -portoffset 4
+   % backup labeltape -size 2048M -portoffset 4
+   % backup labeltape -size 2097152 -portoffset 4
+   
+

Privilege Required +

Related Information +

backup readlabel +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf080.htm b/doc/html/AdminReference/auarf080.htm new file mode 100644 index 0000000..0325d88 --- /dev/null +++ b/doc/html/AdminReference/auarf080.htm @@ -0,0 +1,138 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup listdumps

Purpose + + + + + + + + +

Displays the dump hierarchy from the Backup Database +

Synopsis +

backup listdumps  [-localauth]  [-cell <cell name>]  [-help]
+  
+backup listd  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup listdumps command displays the dump hierarchy from +the Backup Database. +

Options +

-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 output displays the complete dump hierarchy and indicates the +relationship between full and incremental dump levels. Full dump levels +appear at the left margin. The hierarchy can include more than one full +dump level; each one defines a subhierarchy of dump levels that can be +used for dumping different volume sets. +

Incremental dump levels appear below and indented to the right of their +parent dump levels, which can be either full or incremental. Since +multiple incremental dump levels can share the same parent, an incremental +dump level is not always directly below its parent; the amount of +indentation indicates the parent/child relationship. +

If a dump level has an associated expiration date, it appears along with +the level name. Absolute expiration dates appear in the format +

   dump_level expires at day month date time year    
+   
+

and relative expiration dates in the format +

   dump_level expires in {yearsy | monthsm | daysd}
+   
+

to indicate the number of years, months, days, or combination of the three +after creation a dump expires when created at this level. +

Examples +

The following example depicts six dump hierarchies. The expiration +date for all incremental dump levels is 13 days so that the corresponding +tapes can be recycled two weeks after their creation. The expiration +dates for all full dump levels is 27 days so that the corresponding tapes can +be recycled four weeks after their creation. +

   % backup listdumps
+   /week1  expires in  27d
+         /tuesday  expires in  13d
+                 /thursday  expires in  13d
+         /sunday  expires in  13d
+                /tuesday expires in  13d
+                        /thursday expires in  13d
+   /week3  expires in  27d
+         /tuesday  expires in  13d
+                 /thursday  expires in  13d
+         /sunday  expires in  13d
+                /tuesday  expires in  13d
+                        /thursday  expires in  13d
+   /sunday1  expires in  27d
+           /monday1  expires in  13d
+           /tuesday1  expires in  13d 
+           /wednesday1  expires in  13d
+           /thursday1  expires in  13d
+           /friday1  expires in  13d
+   /sunday2  expires in  27d
+           /monday2  expires in  13d
+           /tuesday2  expires in  13d
+           /wednesday2  expires in  13d
+           /thursday2  expires in  13d
+           /friday2  expires in  13d
+   /sunday3  expires in  27d
+           /monday1  expires in  13d
+           /tuesday1  expires in  13d 
+           /wednesday1  expires in  13d
+           /thursday1  expires in  13d
+           /friday1  expires in  13d
+   /sunday4  expires in  27d
+           /monday2  expires in  13d
+           /tuesday2  expires in  13d
+           /wednesday2  expires in  13d
+           /thursday2  expires in  13d
+           /friday2  expires in  13d
+   
+

Privilege Required +

Related Information +

backup adddump +

backup deldump +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf081.htm b/doc/html/AdminReference/auarf081.htm new file mode 100644 index 0000000..a87875a --- /dev/null +++ b/doc/html/AdminReference/auarf081.htm @@ -0,0 +1,101 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup listhosts

Purpose + + + + + + + + + +

Lists Tape Coordinator machines registered in the Backup Database +

Synopsis +

backup listhosts [-localauth]  [-cell <cell name>]  [-help]
+  
+backup listh [-l]  [-c <cell name>]  [-h]
+

Description +

The backup listhosts command displays the Backup Database record +of the port offset numbers defined for Tape Coordinator machines. A +Tape Coordinator must have an entry in the list to be available for backup +operations. +

The existence of an entry does not necessarily indicate that the Tape +Coordinator process (butc) is currently running at that port +offset. To check, issue the backup status command. +

Options +

-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 +

After a Tape hosts: header, the output reports +two things about each Tape Coordinator currently defined in the Backup +Database: +

The hostname of the machine housing the Tape Coordinator. The +format of this name depends on the hostname format used when the backup +addhost command was issued. +
The Tape Coordinator's port offset number. +

The Tape Coordinators appear in the order in which they were added to the +Backup Database. +

Examples +

The following example shows the result of the command in the ABC +Corporation cell: +

   % backup listhosts
+   Tape hosts:
+       Host backup1.abc.com, port offset 0
+       Host backup1.abc.com, port offset 1
+       Host backup3.abc.com, port offset 4
+       Host backup2.abc.com, port offset 3
+   
+

Privilege Required +

Related Information +

backup addhost +

backup delhost +

backup status +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf082.htm b/doc/html/AdminReference/auarf082.htm new file mode 100644 index 0000000..37eec26 --- /dev/null +++ b/doc/html/AdminReference/auarf082.htm @@ -0,0 +1,103 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup listvolsets

+ + + + + + +

Purpose +

Lists volume set entries from the Backup Database +

Synopsis +

backup listvolsets [-name <volume set name>]
+                   [-localauth]  [-cell <cell name>]  [-help]
+   
+backup listv [-n <volume set name>]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup listvolsets command displays the Backup Database +records for either +

All volume sets and their volume entries, if the -name argument +is omitted +
The volume set specified by the -name argument, along with its +volume entries +

Options +

-name +: Names the volume set to display. If this argument is omitted, the +output lists all volume sets defined in 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. +

Output +

The entry for each volume set begins with the Volume set header +and the volume set's name. A temporary volume set's name is +followed by the string (temporary). Each volume entry +follows on a separate line, indicating the entry's index number and the +server, partition, and volume names it matches. The output uses the +metacharacter notation described on the backup addvolentry +reference page. Use the index number to identify volume entries when +deleting them with the backup delvolentry command. +

Examples +

The following example shows the volume entries in the three volume sets +currently defined in the Backup Database: +

   % backup listvolsets
+   Volume set user:
+       Entry   1: server .*, partition .*, volumes: user.*\.backup
+   Volume set sun
+       Entry   1: server .*, partition .*, volumes: sun4x_55\..*
+       Entry   2: server .*, partition .*, volumes: sun4x_56\..*
+   Volume set rs
+       Entry   1: server .*, partition .*, volumes: rs_aix42\..*
+   
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf083.htm b/doc/html/AdminReference/auarf083.htm new file mode 100644 index 0000000..d2d710a --- /dev/null +++ b/doc/html/AdminReference/auarf083.htm @@ -0,0 +1,83 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup quit

+ + + + + + +

Purpose +

Leaves interactive mode +

Synopsis +

quit  [-help]
+  
+q [-h]
+   
+

Description +

The (backup) quit command exits interactive mode, returning the +issuer to the regular shell prompt at which the backup or +backup interactive command was issued to enter interactive +mode. The command has no effect when issued outside interactive +mode. Issuing the <Ctrl-d> command also exits interactive +mode. +

Cautions +

To exit interactive mode, all jobs must be completed. Use the +(backup) jobs command to list any jobs currently pending or +executing, and the (backup) kill command to terminate them as +necessary. +

Options +

-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 exits interactive mode: +

   backup> quit
+   %
+   
+

Privilege Required +

None +

Related Information +

backup interactive +

backup jobs +

backup kill +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf084.htm b/doc/html/AdminReference/auarf084.htm new file mode 100644 index 0000000..22ab1a9 --- /dev/null +++ b/doc/html/AdminReference/auarf084.htm @@ -0,0 +1,216 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup readlabel

+ + + + + + + + +

Purpose +

Reads and displays a tape's label +

Synopsis +

backup readlabel [-portoffset <TC port offset>]
+                 [-localauth]  [-cell <cell name>]  [-help]
+   
+backup rea [-p <TC port offset>]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup readlabel command displays information from the +magnetic tape label of a tape. The information includes the tape's +name (either a permanent name, or an AFS tape name that +reflects the tape's contents in a prescribed format) and its +capacity. +

If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file associated with the +specified port offset, then the backup readlabel command reads the +label information from the first 16 KB block in the backup data file listed +for that port offset in the Tape Coordinator's +/usr/afs/backup/tapeconfig file, rather than from the beginning of +a tape. +

Options +

-portoffset +: Specifies the port offset number of the Tape Coordinator handling the +tapes for this operation. +
-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 +

Output from this command appears in both the shell window where the command +is issued, and in the Tape Coordinator window. +

If the tape is unlabeled or if the specified tape device is empty, the +output reads +

   Failed to read tape label.
+   
+

Otherwise, the output in the shell window has the following format: +

   Tape read was labelled: tape name (dump id)
+        size: size Kbytes
+    
+

where tape name is the permanent name if the tape has one, or the +AFS tape name otherwise. The dump ID is dump ID of the initial +dump on the tape, and size is the recorded capacity of the tape in +kilobytes. +

The output in the Tape Coordinator windows is bounded by an underlined +Tape label header at the top, and the following string +at the bottom: +

   -- End of tape label --
+   
+

In between are lines reporting the following information: +

tape name +

The permanent name assigned by using the -pname argument of the +backup labeltape command. This name remains on the tape +until that argument is used again, no matter how many times the tape is +recycled or otherwise relabeled. If the tape does not have a permanent +name, the value <NULL> appears in this field. +

AFS tape name +

A tape name in one of the following prescribed formats. The Backup +System automatically writes the appropriate AFS tape name to the label as part +of a backup dump or backup savedb operation, or the +operator can assign it with the -name argument to the backup +labeltape command. +

volume_set_name.dump_level_name.tape_index, +if the tape contains volume data. The volume_set_name is the +name of the volume set that was dumped to create the initial dump in the dump +set of to which this tape belongs; dump_level_name is the last +pathname element of the dump level at which the initial dump was backed +up; and tape_index is the numerical position of the tape in the +dump set. +
Ubik.db.dump.tape_index if the +tape contains a dump of the Backup Database, created with the backup +savedb command. The tape_index is the ordinal of the +tape in the dump set. +
<NULL> if the tape has no AFS tape name. This is +normally the case if the -name argument was not included the last +time the backup labeltape command was used on this tape, and no +data has been written to it since. +

creationTime +

The date and time at which the Backup System started performing the dump +operation that created the initial dump. +

cell +

The cell in which the dump set was created. This is the cell whose +Backup Database contains a record of the dump set. +

size +

The tape's capacity (in kilobytes) as recorded on the label, rather +than the amount of data on the tape. The value is assigned by the +-size argument to the backup labeltape command or +derived from the /usr/afs/backup/tapeconfig file on the Tape +Coordinator machine, not from a measurement of the tape. +

dump path +

The dump level of the initial dump in the dump set +

dump id +

The dump ID number of the initial dump in the dump set, as recorded in the +Backup Database +

useCount +

The number of times a dump has been written to the tape, or it has been +relabeled +

The message ReadLabel: Finished indicates the completion +of the output. +

Examples +

The following example shows the output for the tape with permanent name +oct.guest.dump and capacity 2 MB, expressed in +kilobyte units (2097152 equals 2 times 1024²). +

   % backup readlabel -portoffset 6
+   Tape read was labelled: oct.guest.dump (907215000)
+        size: 2097152 Kbytes
+   
+

The output in the Tape Coordinator window reads: +

   Tape label
+   ----------
+   tape name = oct.guest.dump
+   AFS tape name = guests.monthly.3
+   creationTime = Thu Oct 1 00:10:00 1998
+   cell = abc.com
+   size = 2097152 Kbytes
+   dump path = /monthly
+   dump id = 907215000
+   useCount = 5
+   ---- End of tape label ----
+   
+

The following example is for a tape that does not have a permanent +tape. +

   % backup readlabel -portoffset 6
+   Tape read was labelled: guests.monthly.2 (909899900)
+        size: 2097152 Kbytes
+   
+

The output in the Tape Coordinator window reads: +

   Tape label
+   ----------
+   tape name = <NULL>
+   AFS tape name = guests.monthly.2
+   creationTime = Sun Nov 1 00:58:20 1998
+   cell = abc.com
+   size = 2097152 Kbytes
+   dump path = /monthly
+   dump id = 909899900
+   useCount = 1
+   ---- End of tape label ----
+   
+

Privilege Required +

Related Information +

backup labeltape +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf085.htm b/doc/html/AdminReference/auarf085.htm new file mode 100644 index 0000000..2902fb1 --- /dev/null +++ b/doc/html/AdminReference/auarf085.htm @@ -0,0 +1,117 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup restoredb

+ + + +

Purpose +

Restores a saved copy of the Backup Database +

Synopsis +

backup restoredb [-portoffset <TC port offset>]
+                 [-localauth]  [-cell <cell name>]  [-help]
+  
+backup res [-p <TC port offset>]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup restoredb command restores to the Backup Server +machine's local disk a version of the Backup Database previously written +to tape by using the backup savedb command. +

(If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file associated with the +specified port offset, then the backup restoredb command restores +data from the backup data file listed for that port offset in the Tape +Coordinator's /usr/afs/backup/tapeconfig file, instead of from +tape. For the sake of clarity, the following text refers to tapes only, +but the Backup System handles backup data files in much the same way.) +

The most common reason to run this command is to replace a corrupted or +otherwise damaged Backup Database; use the backup dbverify +command to determine the database's status. The command can also +be used to restore records that were removed from the database when the +-archive argument was included on a previous backup +savedb command. +

The command completely overwrites the existing Backup Database records for +volume sets, Tape Coordinators, and the dump hierarchy with the corresponding +information from the saved version. It does not overwrite existing dump +records, but instead interleaves the records from the copy being +restored. If both the existing database (on the Backup Server +machine's disk) and the copy being restored include a record about the +same dump, the Backup System retains the one in the existing database. +

The Tape Coordinator's default response to this command is to access +the first tape it needs by invoking the MOUNT instruction in the +local /usr/afs/backup/CFG_device_name file, or by +prompting the backup operator to insert the tape if there is no +MOUNT instruction. However, if the AUTOQUERY NO +instruction appears in the CFG_device_name file, or if the +issuer of the butc command included the -noautoquery +flag, the Tape Coordinator instead expects the tape to be in the device +already. If it is not, or is the wrong tape, the Tape Coordinator +invokes the MOUNT instruction or prompts the operator. It +also invokes the MOUNT instruction or prompts for any additional +tapes needed to complete the restore operation; the backup operator must +arrange to provide them. +

Cautions +

If the database is corrupted, do not attempt to restore a saved database on +top of it. Instead, use the instructions for repairing a corrupted +database in the IBM AFS Administration Guide chapter about +performing backup operations. +

Options +

-portoffset +: Specifies the port offset number of the Tape Coordinator handling the +tapes for this operation. +
-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 example shows the Backup Database being restored from the +Tape Coordinator with port offset 0: +

   % backup restoredb
+   
+

Privilege Required +

Related Information +

backup dbverify +

backup savedb +

butc +

IBM AFS Administration Guide +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf086.htm b/doc/html/AdminReference/auarf086.htm new file mode 100644 index 0000000..bf69d18 --- /dev/null +++ b/doc/html/AdminReference/auarf086.htm @@ -0,0 +1,151 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup savedb

+ + + +

Purpose +

Creates a saved copy of the Backup Database +

Synopsis +

backup savedb [-portoffset <TC port offset>]  [-archive <date time>⁺]
+              [-localauth]  [-cell <cell name>]  [-help]
+  
+backup sa  [-p <TC port offset>]  [-a <date time>⁺]
+           [-l]  [-c <cell name>]  [-h]
+

Description +

The backup savedb command creates a backup copy of the entire +Backup Database and writes it to the tape in the device controlled by the Tape +Coordinator indicated with the -portoffset argument. If the +database is damaged (as reported by the backup dbverify command), +this command repairs as much of the corruption as possible as it creates the +saved copy. The Backup Server creates a dump record for the saved +database in the Backup Database (but in the disk version of the database only, +not in the version written to tape). +

If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file associated with the +specified port offset, then the backup savedb command dumps the +database copy to the backup data file listed for that port offset in the Tape +Coordinator's /usr/afs/backup/tapeconfig file, instead of to +tape. For the sake of clarity, the following text refers to tapes only, +but the Backup System handles backup data files in much the same way. +

If the -archive flag is provided, after writing the saved copy +of the database the Backup System truncates the copy of the database on disk +by deleting volume dump records with timestamps prior to the specified date +and time (it does not delete the dump records created by previous backup +savedb commands, however). +

If the tape to which the database copy is written has an AFS tape name, it +must be Ubik_db_dump.1 or <NULL>. Any +permanent name is acceptable. +

The Tape Coordinator's default response to this command is to access +the first tape by invoking the MOUNT instruction in the local +/usr/afs/backup/CFG_device_name file, or by prompting the +backup operator to insert the tape if there is no MOUNT +instruction. However, if the AUTOQUERY NO instruction +appears in the CFG_device_name file, or if the issuer of +the butc command included the -noautoquery flag, the +Tape Coordinator instead expects the tape to be in the device already. +If it is not, the Tape Coordinator invokes the MOUNT instruction or +prompts the operator. It also invokes the MOUNT instruction +or prompts for any additional tapes needed to complete the operation; the +backup operator must arrange to provide them. +

Options +

-portoffset +

Specifies the port offset number of the Tape Coordinator handling the +tapes for this operation. +

-archive +

Specifies a date and time; volume dump records with earlier +timestamps are deleted from the disk copy of the Backup Database after the +Backup System dumps the database (a dump's timestamp appears in the +created field of the output from the backup dumpinfo +command). However, if a dump set contains any dump created after the +specified date, none of the dump records associated with the dump set are +deleted. Dump records for previous dumps of the database (created with +the backup savedb command) are never deleted; use the +backup deletedump command to remove them. +

Provide one of two values: +

The string NOW to indicate the current date and time, in which +case the Backup System deletes all dump records except those for dumps of the +Backup Database itself. +
A date value in the format mm/dd/yyyy +[hh:MM]. The month (mm), day (dd), and +year (yyyy) are required, and 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 Backup System automatically reduces any later date to the +maximum value. +
The hour and minutes (hh:MM) are optional, but if +provided must be in 24-hour format (for example, the value +14:36 represents 2:36 p.m.). If +omitted, the time defaults to 59 seconds after midnight (00:00:59 +hours). Similarly, the backup command interpreter +automatically adds 59 seconds to any time value provided. In both +cases, adding 59 seconds compensates for how the Backup Database and +backup dumpinfo command represent dump creation times in hours and +minutes only. That is, the Database records a creation timestamp of +20:55 for any dump created between 20:55:00 and +20:55:59. Automatically adding 59 seconds to a time thus +includes the records for all dumps created during that minute. +

Note:

-localauth +

-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 example writes a copy of the Backup Database to the tape +device controlled by the Tape Coordinator with port offset 1: +

   % backup savedb -portoffset 1
+   
+

Privilege Required +

Related Information +

backup dbverify +

backup restoredb +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf087.htm b/doc/html/AdminReference/auarf087.htm new file mode 100644 index 0000000..488be67 --- /dev/null +++ b/doc/html/AdminReference/auarf087.htm @@ -0,0 +1,292 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup scantape

+ + + + + + +

Purpose +

Extracts dump information from a tape +

Synopsis +

backup scantape [-dbadd]  [-portoffset <TC port offset>]
+                [-localauth]  [-cell <cell name>]  [-help]
+  
+backup sc [-d]  [-p <TC port offset>]  [-l]  [-c <cell name>]  [-help]
+

Description +

The backup scantape command extracts information from the dump +labels and volume headers on the tape in the device controlled by the Tape +Coordinator indicated by the -portoffset argument. The Tape +Coordinator displays the information for each volume in its window as soon as +it extracts it (rather than waiting until it has scanned the entire +tape). +

(If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file associated with the +specified port offset, then the backup scantape command extracts +dump information from the backup data file named in that port offset's +entry in the /usr/afs/backup/tapeconfig file on the Tape +Coordinator machine, rather than from a tape. For the sake of clarity, +the following text refers to tapes only, but the Backup System handles backup +data files in much the same way.) +

If the -dbadd flag is provided, the backup scantape +command creates new dump and volume records in the Backup Database for the +scanned information. However, if it finds that a record already exists +in the database for the same dump, it terminates the scanning +operation. +

The scanning operation works only on tapes containing volume data. +The command fails with an error message if the tape contains a copy of the +Backup Database (was created with the backup savedb command, or has +the AFS tape name Ubik_db_dump.1). +

The Tape Coordinator's default response to this command is to access +the tape by invoking the MOUNT instruction in the +CFG_device_name file, or by prompting the backup operator +to insert the tape if there is no MOUNT instruction. +However, if the AUTOQUERY NO instruction appears in the +CFG_device_name file, or if the issuer of the +butc command included the -noautoquery flag, the Tape +Coordinator instead expects the tape to be in the device already. If it +is not, the Tape Coordinator invokes the MOUNT instruction or +prompts the operator. +

To terminate a tape scanning operation in interactive mode, issue the +(backup) kill command. In noninteractive mode, the only +choice is to use a termination signal such as <Ctrl-c> to halt +the Tape Coordinator completely. +

Cautions +

A scanning operation does not have to begin with the first tape in a dump +set, but the Backup System can process tapes only in sequential order after +the initial tape provided. The Tape Coordinator automatically requests +any subsequent tapes by invoking the MOUNT instruction in the local +/usr/afs/backup/CFG_device_name file, or by prompting the +operator if there is no MOUNT instruction. +

The Tape Coordinator's success in scanning a tape that is corrupted or +damaged depends on the extent of the damage and what type of data is +corrupted. It can almost always scan the tape successfully up to the +point of damage. If the damage is minor, the Tape Coordinator can +usually skip over it and scan the rest of the tape, but more major damage can +prevent further scanning. Because a scanning operation can start on any +tape in a dump set, damage on one tape does not prevent scanning of the others +in the dump set. However, it is possible to scan either the tapes that +precede the damaged one or the ones that follow it, but not both. +

If a tape is relabeled with the backup labeltape command, it is +not possible to recover data from it for the purposes of rebuilding the Backup +Database. +

If the -dbadd flag is included on the command, it is best not to +terminate the tape scanning operation before it completes (for example, by +issuing the (backup) kill command in interactive mode). The +Backup System writes a new record in the Backup Database for each dump as soon +as it scans the relevant information on the tape, and so it possibly has +already written new records. If the operator wants to rerun the +scanning operation, he or she must locate and remove the records created +during the terminated operation: the second operation exits +automatically if it finds that a record that it needs to create already +exists. +

If the -dbadd flag is included and the first tape provided is +not the first tape in the dump set, the following restrictions apply: +

If the first data on the tape is a continuation of a volume that begins on +the previous (unscanned) tape in the dump set, the Backup System does not add +a record for that volume to the Backup Database. +
The Backup System must read the marker that indicates the start of an +appended dump to add database records for the volumes in it. If the +first volume on the tape belongs to an appended dump, but is not immediately +preceded by the appended-dump marker, the Backup System does not create a +Backup Database record for it or any subsequent volumes that belong to that +appended dump. +

Options +

-dbadd +: Adds the information extracted from the tape to the Backup Database (but +only if the database does not already contain an entry with the same dump ID +number). +
-portoffset +: Specifies the port offset number of the Tape Coordinator handling the +tapes for this operation. +
-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 +

For every dump on a tape, the backup scantape command displays +in the Tape Coordinator window the dump label and the volume header of each +volume in the dump. If a dump spans more than one tape, the dump label +does not repeat at the beginning of subsequent tapes. +

A dump label contains the following fields, which are the same as in the +output from the backup readlabel command: +

tape name +

AFS tape name +

A tape name in one of the following prescribed formats. The Backup +System automatically writes the appropriate AFS tape name to the label as part +of a backup dump operation, or the operator can assign it with the +-name argument to the backup labeltape command. +

volume_set_name.dump_level_name.tape +_index, if the tape contains volume data. The +volume_set_name is the name of the volume set that was dumped to +create the initial dump in the dump set of which this tape is a part; +dump_level_name is the last pathname element of the dump level at +which the initial dump was backed up; and tape_index is the +numerical position of the tape in the dump set. +
<NULL> if the tape has no AFS tape name. This is +normally the case if the -name argument was not included the last +time the backup labeltape command was used on this tape, and no +data has been written to it since. +

creationTime +

The date and time at which the Backup System started performing the dump +operation that created the initial dump. +

cell +

The cell in which the dump set was created. This is the cell whose +Backup Database contains a record of the dump set. +

size +

dump path +

The dump level of the initial dump in the dump set. +

dump id +

The dump ID number of the initial dump in the dump set, as recorded in the +Backup Database. +

useCount +

The number of times a dump has been written to the tape, or it has been +relabeled. +

The volume header contains the following fields: +

volume name +: The volume name, complete with a .backup or +.readonly extension, if appropriate. +
volume ID +: The volume's volume ID. +
dumpSetName +: The dump to which the volume belongs. The dump name is of the form +volume_set_name.dump_level_name and +matches the name displayed in the dump label. +
dumpID +: The dump ID of the dump named in the dumpSetName field. +
level +: The depth in the dump hierarchy of the dump level used in creating the +dump. A value of 0 indicates a full dump. A value of +1 or greater indicates an incremental dump made at the indicated +depth in the hierarchy. The value reported is for the entire dump, not +necessarily for the volume itself; for example, it is possible for a dump +performed at an incremental level to include a full dump of an individual +volume if the volume was omitted from previous dumps. +
parentID +: The dump ID number of dumpSetName's parent dump. It +is 0 if the value in the level field is +0. +
endTime +: Is always 0; it is reserved for internal use. +
cloneDate +: The date and time at which the volume was created. For a backup or +read-only volume, this represents the time at which it was cloned from its +read/write source. For a read/write volume, it indicates the time at +which the Backup System locked the volume for purposes of including it in the +dump named in the dumpSetName field. +

The message Scantape: Finished indicates the completion of +the output. +

In normal circumstances, the Backup System writes a marker to indicate that +a volume is the last one on a tape, or that the volume continues on the next +tape. However, if a backup operation terminated abnormally (for +example, because the operator terminated the Tape Coordinator by issuing the +<Ctrl-c> command during the operation), then there is no such +marker. Some very early versions of the Backup System also did not +write these markers. If a tape does not conclude with one of the +expected markers, the Tape Coordinator cannot determine if there is a +subsequent tape in the dump set and so generates the following message in its +window: +

   Are there more tapes? (y/n)
+   
+

Examples +

The following example shows the output for the first two volumes on a tape +in the device with port offset 0: +

   % backup scantape
+   Dump label
+   ----------
+   tape name = monthly_guest
+   AFS tape name = guests.monthly.3
+   creationTime =  Mon Feb  1 04:06:40 1999
+   cell = abc.com
+   size = 2150000 Kbytes
+   dump path = /monthly
+   dump id = 917860000
+   useCount = 44
+   -- End of dump label --
+   -- volume --
+   volume name: user.guest10.backup
+   volume ID 1937573829
+   dumpSetName: guests.monthly
+   dumpID 917860000
+   level 0
+   parentID 0
+   endTime 0
+   clonedate Mon Feb  1 03:03:23 1999
+   -- volume --
+   volume name: user.guest11.backup
+   volume ID 1938519386
+   dumpSetName: guests.monthly
+   dumpID 917860000
+   level 0
+   parentID 0
+   endTime 0
+   clonedate Mon Feb  1 03:05:15 1999
+   
+

Privilege Required +

Related Information +

backup dump +

backup dumpinfo +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf088.htm b/doc/html/AdminReference/auarf088.htm new file mode 100644 index 0000000..a4d79ef --- /dev/null +++ b/doc/html/AdminReference/auarf088.htm @@ -0,0 +1,160 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup setexp

+ + + + + + +

Purpose +

Sets the expiration date for existing dump levels. +

Synopsis +

backup setexp -dump <dump level name>⁺  [-expires <expiration date>⁺]
+              [-localauth]  [-cell <cell name>]  [-help]
+  
+backup se -d <dump level name>⁺  [-e <expiration date>⁺]
+          [-l]  [-c <cell name>]  [-h]
+

Description +

The backup setexp command sets or changes the expiration date +associated with each specified dump level, which must already exist in the +dump hierarchy. +

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. +

If the command is used to change an existing expiration date associated +with a dump level, the new date applies only to dumps created after the +change. Existing dumps retain the expiration date assigned at the time +they were created. +

Options +

-dump +

Specifies the full pathname of each dump level to assign the expiration +date specified by the -expires argument. +

-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] }
+   
+

Relative expiration dates have the following format: +

   [in] [yearsy] [monthsm] [daysd]
+   
+

-localauth +

-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 example associates an absolute expiration date of 10:00 +p.m. on 31 December 1999 with the dump level +/1998/december: +

   % backup setexp -dump /1998/december -expires at 12/31/1999 22:00
+   
+

The following example associates a relative expiration date of 7 days with +the two dump levels /monthly/week1 and +/monthly/week2: +

   % backup setexp -dump /monthly/week1 /monthly/week -expires 7d
+   
+

Privilege Required +

Related Information +

backup adddump +

backup deldump +

backup listdumps +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf089.htm b/doc/html/AdminReference/auarf089.htm new file mode 100644 index 0000000..4b26ce6 --- /dev/null +++ b/doc/html/AdminReference/auarf089.htm @@ -0,0 +1,145 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup status

+ + + + +

Purpose +

Reports a Tape Coordinator's status +

Synopsis +

backup status [-portoffset <TC port offset>]
+              [-localauth]  [-cell <cell name>]  [-help]
+  
+backup st [-p <TC port offset>]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup status command displays which operation, if any, the +indicated Tape Coordinator is currently executing. +

Options +

-portoffset +: Specifies the port offset number of the Tape Coordinator for which to +report the status. +
-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 following message indicates that the Tape Coordinator is not currently +performing an operation: +

   Tape coordinator is idle
+

Otherwise, the output includes a message of the following format for each +running or pending operation: +

   Task task_ID:  operation:   status
+

where +

task_ID +

Is a task identification number assigned by the Tape Coordinator. +It begins with the Tape Coordinator's port offset number. +

operation +

Identifies the operation the Tape Coordinator is performing, which is +initiated by the indicated command: +

Dump (the backup dump command) +
Restore (the backup diskrestore, backup +volrestore, or backup volsetrestore commands) +
Labeltape (the backup labeltape command) +
Scantape (the backup scantape command) +
SaveDb (the backup savedb command) +
RestoreDb (the backup restoredb command) +

status +

Indicates the job's current status in one of the following +messages. +

number Kbytes transferred, volume volume_name +: For a running dump operation, indicates the number of kilobytes copied to +tape or a backup data file so far, and the volume currently being +dumped. +
number Kbytes, restore.volume +: For a running restore operation, indicates the number of kilobytes copied +into AFS from a tape or a backup data file so far. +
[abort requested] +: The (backup) kill command was issued, but the termination +signal has yet to reach the Tape Coordinator. +
[abort sent] +: The operation is canceled by the (backup) kill command. +Once the Backup System removes an operation from the queue or stops it from +running, it no longer appears at all in the output from the command. +
[butc contact lost] +: The backup command interpreter cannot reach the Tape +Coordinator. The message can mean either that the Tape Coordinator +handling the operation was terminated or failed while the operation was +running, or that the connection to the Tape Coordinator timed out. +
[done] +: The Tape Coordinator has finished the operation. +
[drive wait] +: The operation is waiting for the specified tape drive to become +free. +
[operator wait] +: The Tape Coordinator is waiting for the backup operator to insert a tape +in the drive. +

   XBSA_program Tape coordinator
+

where XBSA_program is the name of the XBSA-compliant +program. +

Examples +

The following example shows that the Tape Coordinator with port offset 4 +has so far dumped about 1.5 MB of data for the current dump operation, +and is currently dumping the volume named +user.pat.backup: +

   % backup status -portoffset 4
+   Task 4001:  Dump:   1520 Kbytes transferred,  volume user.pat.backup
+   
+

Privilege Required +

Related Information +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf090.htm b/doc/html/AdminReference/auarf090.htm new file mode 100644 index 0000000..1185524 --- /dev/null +++ b/doc/html/AdminReference/auarf090.htm @@ -0,0 +1,121 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup volinfo

+ + + + + + +

Purpose +

Displays a volume's dump history from the Backup Database +

Synopsis +

backup volinfo -volume <volume name>
+               [-localauth]  [-cell <cell name>]  [-help]
+  
+backup voli -v <volume name>  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup volinfo command displays a dump history of the +specified volume, reporting information such as the date on which the volume +was dumped and the tapes that contain it. Include the +.backup extension on the volume name if the backup version +of the volume was dumped. +

Options +

-volume +: Names the volume for which to display the dump history. Include +the .backup or .readonly extension if the +backup or read-only version of the volume was dumped. +
-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 +

dumpID +: The dump ID of the dump that includes the volume. +
lvl +: The depth in the dump hierarchy of the dump level at which the volume was +dumped. A value of 0 indicates a full dump. A value +of 1 or greater indicates an incremental dump made at the specified +depth in the dump hierarchy. +
parentid +: The dump ID of the dump's parent dump. A value of 0 +indicates a full dump, which has no parent; in this case, the value in +the lvl column is also 0. +
creation date +: The date and time at which the Backup System started the dump operation +that created the dump. +
clone date +: For a backup or read-only volume, the time at which it was cloned from its +read/write source. For a read/write volume, the same as the value in +the creation date field. +
tape name +: The name of the tape containing the dump: either the permanent tape +name, or an AFS tape name in the format +volume_set_name.dump_level_name.tape_index +where volume_set_name is the name of the volume set associated with +the initial dump in the dump set of which this tape is a part; +dump_level_name is the name of the dump level at which the initial +dump was backed up; tape_index is the ordinal of the tape in +the dump set. Either type of name can be followed by a dump ID in +parentheses; if it appears, it is the dump ID of the initial dump in the +dump set to which this appended dump belongs. +

Examples +

The following example shows part of the dump history of the Backup volume +user.smith.backup: +

   % backup volinfo -volume user.smith.backup
+   DumpID    lvl parentID  creation date    clone date       tape name
+   924600000 1   924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
+   924514392 1   924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2 
+   924427600 0           0 04/18/1999 05:26 04/18/1999 04:58 user_full_6 
+       .     .      .         .       .       .      .         .
+       .     .      .         .       .       .      .         .
+   
+

Privilege Required +

None +

Related Information +

backup dumpinfo +

backup volrestore +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf091.htm b/doc/html/AdminReference/auarf091.htm new file mode 100644 index 0000000..7451a1f --- /dev/null +++ b/doc/html/AdminReference/auarf091.htm @@ -0,0 +1,290 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup volrestore

+ + + + + + +

Purpose +

Restores one or more volumes +

Synopsis +

backup volrestore -server <destination machine>
+                  -partition <destination partition>
+                  -volume <volume(s) to restore>⁺  
+                  [-extension <new volume name extension>]
+                  [-date <date from which to restore>⁺]
+                  [-portoffset <TC port offsets>⁺]  [-n]
+                  [-localauth]  [-cell <cell name>]  [-help]
+   
+backup volr -s <destination machine>  -pa <destination partition>
+            -v <volume(s) to restore>⁺  [-e <new volume name extension>]
+            [-d <date from which to restore>⁺]  [-po <TC port offsets>⁺]
+            [-n]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup volrestore command restores the contents of one or +more volumes to the site indicated by the -server and +-partition arguments. Use the command either to overwrite +the contents of existing volumes with the restored data or to create new +volumes while retaining the existing ones. The specified site does not +have to be the current site for the volumes. +

(If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file associated with the +specified port offset, then the backup volrestore command restores +data from the backup data file listed for that port offset in the Tape +Coordinator's /usr/afs/backup/tapeconfig file, rather than +from tape. For the sake of clarity, the following text refers to tapes +only, but the Backup System handles backup data files in much the same +way.) +

The command's arguments can be combined as indicated: +

To preserve a volume's current contents and also create a new volume +to house the restored version, use the -extension argument. +The Backup System creates the new volume on the server and partition named by +the -server and -partition arguments, assigns it the +same name as the current volume with the addition of the specified extension, +and creates a new Volume Location Database (VLDB) entry for it. +Creating a new volume enables the administrator to compare the two +versions. +
To overwrite a volume's existing contents with the restored version, +omit the -extension argument, and specify the site as +indicated: +
- To retain the current site, specify it with the -server and +-partition arguments. +
- To move the volume to a different site while overwriting it, specify the +new site with the -server argument, -partition argument, +or both. The Backup System creates a new volume at that site, removes +the existing volume, and updates the site information in the volume's +VLDB entry. The backup version of the volume is not removed +automatically from the original site, if it exists. Use the vos +remove command to remove it and the vos backup command to +create a backup version at the new site. +
+
To restore a volume that no longer exists in the file system, specify its +name with the -volume argument and use the -server and +-partition arguments to place it at the desired site. The +Backup System creates a new volume and new VLDB entry. +

In each case, the command sets each volume's creation date to the date +and time at which it restores it. The creation date appears in the +Creation field in the output from the vos examine and +vos listvol commands. +

If restoring all of the volumes that resided on a single partition, it is +usually more efficient to use the backup diskrestore +command. If restoring multiple volumes to many different sites, it can +be more efficient to use the backup volsetrestore command. +

By default, the backup volrestore command restores the most +recent full dump and all subsequent incremental dumps for each volume, +bringing the restored volumes to the most current possible state. To +restore the volumes to their state at some time in the past, use the +-date argument. The Backup System restores the most recent +full dump and each subsequent incremental dump for which the clone +date of the volume included in the dump is before the indicated date and +time (the clone date timestamp appears in the clone date field of +the output from the backup volinfo command). For backup and +read-only volumes, the clone date represents the time at which the volume was +copied from its read/write source; for read/write volumes, it represents +the time at which the volume was locked for inclusion in the dump. The +resemblance of a restored volume to its actual state at the indicated time +depends on the amount of time that elapsed between the volume's clone +date in the last eligible dump and the specified time. +

If the -volume argument specifies the base (read/write) form of +the volume name, the Backup System searches the Backup Database for the newest +dump set that includes a dump of either the read/write or the backup version +of the volume. It restores the dumps of that version of the volume, +starting with the most recent full dump. If, in contrast, the volume +name explicitly includes the .backup or +.readonly extension, the Backup System restores dumps of the +corresponding volume version only. +

To generate a list of the tapes the Backup System needs to perform the +restore operation, without actually performing it, combine the -n +flag with the options to be used on the actual command. +

If all of the full and incremental dumps of all relevant volumes were not +written to a type of tape that a single Tape Coordinator can read, use the +-portoffset argument to list multiple port offset numbers in the +order in which the tapes are needed (first list the port offset for the full +dump, second the port offset for the level 1 incremental dump, and so +on). If restoring multiple volumes, the same ordered list of port +offsets must apply to all of them. If not, either issue this command +separately for each volume, or use the vos volsetrestore command +after defining groups of volumes that were dumped to compatible tape +types. For further discussion, see the IBM AFS Administration +Guide. +

Options +

-server +

Names the file server machine on which to restore each volume. If +this argument and the -partition argument indicate a site other +than the current site for each volume, and the -extension argument +is not also provided, the Backup System removes the existing volumes from +their current sites, places the restored contents at the specified site, and +changes the site information in the volume's VLDB entry. +

-partition +

Names the partition to which to restore each volume. If this +argument and the -server argument indicate a site other than the +current site for each volume, and the -extension argument is not +also provided, the Backup System removes the existing volumes from their +current sites, places the restored contents at the specified site, and changes +the site information in the volume's VLDB entry. +

-volume +

Names one or more volumes to restore, using the volume name as listed in +the Backup Database. Provide the base (read/write) name of each volume +to have the Backup System search the Backup Database for the newest dump set +that includes a dump of either the read/write or the backup version of the +volume; it restores the dumps of that version of the volume, starting +with the most recent full dump. If, in contrast, a volume name +explicitly includes the .backup or +.readonly extension, the Backup System restores dumps of the +corresponding volume version only. +

-extension +

Creates a new volume to house the restored data, with a name derived by +appending the specified string to each volume named by the -volume +argument. The Backup System creates a new VLDB entry for the +volume. Any string other than .readonly or +.backup is acceptable, but the combination of the existing +volume name and extension cannot exceed 22 characters in length. To use +a period to separate the extension from the name, specify it as the first +character of the string (as in .rst, for example). +

-date +

Specifies a date and optionally time; the restored volume includes +data from dumps performed before the date only. Provide a value in the +format mm/dd/yyyy [hh:MM], +where the required mm/dd/yyyy portion indicates the month +(mm), day (dd), and year (yyyy), and the optional +hh:MM portion indicates the hour and minutes in 24-hour format +(for example, the value 14:36 represents 2:36 +p.m.). If omitted, the time defaults to 59 seconds after +midnight (00:00:59 hours). +

If this argument is omitted, the Backup System restores all possible dumps +including the most recently created. +
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. +
+

-portoffset +

Provide this argument unless the default value of 0 (zero) is appropriate +for all dumps. If 0 is just one of the values in the list, +provide it explicitly in the appropriate order. +

-n +

Displays the list of tapes that contain the dumps required by the restore +operation, without actually performing the operation. +

-localauth +

-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 +

If the issuer includes the -n flag with the command, the +following string appears at the head of the list of the tapes necessary to +complete the restore operation. +

   Tapes needed:
+   
+

Examples +

The following command restores the volume user.pat to +partition /vicepa on machine +fs5.abc.com: +

   % backup volrestore -server fs5.abc.com -partition a -volume user.pat
+   
+

The following command restores the volumes user.smith and +user.terry to partition /vicepb on machine +fs4.abc.com, adding a .rst +extension to each volume name and preserving the existing +user.smith and user.terry volumes. +Only dumps created before 5:00 p.m. on 31 January 1998 are +restored. (The command is shown here on multiple lines only for +legibility reasons.) +

   % backup volrestore -server fs4.abc.com -partition b  \
+                       -volume user.smith user.terry  \ 
+                       -extension .rst -date 1/31/1998 17:00
+   
+

The following command restores the volume user.pat to +partition /vicepb on machine +fs4.abc.com. The Tape Coordinator with port +offset 1 handles the tape containing the full dump; the Tape Coordinator +with port offset 0 handles all tapes containing incremental dumps. (The +command is shown here on two lines only for legibility reasons.) +

   % backup volrestore -server fs5.abc.com -partition a  \
+                       -volume user.pat -portoffset 1 0
+   
+

Privilege Required +

Related Information +

backup dump +

backup diskrestore +

butc +

vos backup +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf092.htm b/doc/html/AdminReference/auarf092.htm new file mode 100644 index 0000000..0d69fd3 --- /dev/null +++ b/doc/html/AdminReference/auarf092.htm @@ -0,0 +1,352 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

backup volsetrestore

+ + + + + + + +

Purpose +

Restores all volumes in a volume set +

Synopsis +

backup volsetrestore [-name <volume set name>]  [-file <file name>]
+                     [-portoffset <TC port offset>⁺]  
+                     [-extension <new volume name extension>]
+                     [-n]  [-localauth]  [-cell <cell name>]  [-help]
+   
+backup vols [-na <volume set name>]  [-f <file name>]
+            [-p <TC port offset>⁺]  [-e <new volume name extension>]
+            [-n]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup volsetrestore command restores the complete contents +of a group of read/write volumes to the file system, by restoring data from +the last full dump and all subsequent incremental dumps of each volume. +It is most useful for recovering from loss of data on multiple partitions, +since it can restore each of a defined set of volumes to a different +site. +

(If the FILE YES instruction appears in the +/usr/afs/backup/CFG_device_name file associated with the +specified port offset, then the backup volsetrestore command +restores data from the backup data file listed for that port offset in the +Tape Coordinator's /usr/afs/backup/tapeconfig file, instead of +from tape. For the sake of clarity, the following text refers to tapes +only, but the Backup System handles backup data files in much the same +way.) +

If restoring one or more volumes to a single site only, it is usually more +efficient to use the backup volrestore command. If restoring +all volumes that resided on a single partition, it is usually more efficient +to use the backup diskrestore command. +

Indicate the volumes to restore by providing either the -name +argument or the -file argument: +

The -name argument names a volume set. The Backup System +restores all volumes listed in the Volume Location Database (VLDB) that match +the server, partition, and volume name criteria defined in the volume +set's volume entries, and for which dumps are available. It +restores the volumes to their current site (machine and partition), and by +default overwrites the existing volume contents. +
It is not required that the volume set was previously used to back up +volumes (was used as the -volumeset option to the backup +dump command). It can be defined especially to match the volumes +that need to be restored with this command, and that is usually the better +choice. Indeed, a temporary volume set, created by including +the -temporary flag to the backup addvolset command, can +be especially useful in this context. A temporary volume set is not +added to the Backup Database and exists only during the current interactive +backup session, which is suitable if the volume set is needed only to complete +the single restore operation initialized by this command. +
The reason that a specially defined volume set is probably better is that +volume sets previously defined for use in dump operations usually match the +backup version of volumes, whereas for a restore operation it is best to +define volume entries that match the base (read/write) name. In that +case, the Backup System searches the Backup Database for the newest dump set +that includes either the read/write or the backup version of the +volume. If, in contrast, a volume entry explicitly matches the +volume's backup or read-only version, the Backup System restores dumps of +that volume version only. +
The -file argument names a file that lists specific volumes and +the site to which to restore each. The volume name must match the name +used in Backup Database dump records rather than in the VLDB, if they differ, +because the Backup System does not look up volumes in the VLDB. The +specified site can be different than the volume's current one; in +that case, the Backup System removes the current version of the volume and +updates the volume's location information in the VLDB. +

If all of the full and incremental dumps of all relevant volumes were not +written to a type of tape that a single Tape Coordinator can read, use the +-portoffset argument to list multiple port offset numbers in the +order in which the tapes are needed (first list the port offset for the full +dump, second the port offset for the level 1 incremental dump, and so +on). This implies that the full dumps of all relevant volumes must have +been written to a type of tape that the first Tape Coordinator can read, the +level 1 incremental dumps to a type of tape the second Tape Coordinator can +read, and so on. If dumps are on multiple incompatible tape types, use +the backup volrestore command to restore individual volumes, or use +this command after defining new volume sets that group together volumes that +were dumped to compatible tape types. For further discussion, see the +IBM AFS Administration Guide. +

By default, the Backup System overwrites the contents of an existing volume +with the restored data. To create a new volume to house the restored +version instead, use the -extension argument. The Backup +System derives the new volume's name by adding the specified extension to +the read/write base name, and creates a new VLDB entry. The command +does not affect the existing volume in any way. However, if a volume +with the specified extension also already exists, the command overwrites +it. +

The -n flag produces a list of the volumes to be restored if the +-n flag were not included, without actually restoring any +volumes. See the Output section of this reference page for a +detailed description of the output, and suggestions on how to combine it most +effectively with the -file and -name arguments. +

The execution time for a backup volsetrestore command depends on +the number of volumes to be restored and the amount of data in them, but it +can take hours to restore a large number of volumes. One way to reduce +the time is to run multiple instances of the command simultaneously, either +using the -name argument to specify disjoint volume sets for each +command, or the -file argument to name files that list different +volumes. This is possible if there are multiple available Tape +Coordinators that can read the required tapes. Depending on how the +volumes to be restored were dumped to tape, specifying disjoint volume sets +can also reduce the number of tape changes required. +

Options +

-name +

Names a volume set to restore. The Backup System restores all of +the volumes listed in the VLDB that match the volume set's volume +entries. Provide this argument or the -file argument, but +not both. +

-file +

Specifies the full pathname of a file that lists one or more volumes and +the site (file server machine and partition) to which to restore each. +Use either this argument or the -name argument, but not +both. +

Each volume's entry must appear on its own (unbroken) line in the +file, and have the following format: +

    machine  partition
+ volume [comments...]
+   
+

where +

machine +: Names the file server machine to which to restore the volume. +
partition +: Names the partition to which to restore the volume. +
volume +: Names the volume to restore. It is generally best to specify the +base (read/write) name of each volume. In this case, the Backup System +searches the Backup Database for the newest dump set that includes a dump of +either the read/write or the backup version of the volume. It restores +the dumps of that version of the volume, starting with the most recent full +dump. If, in contrast, the name explicitly includes the +.backup or .readonly extension, the Backup +System restores dumps of that volume version only. +
comments... +: Is any other text. The Backup System ignores any text on each line +that appears after the volume name, so this field can be used for notes +helpful to the backup operator or other administrator. +

-extension +

Creates a new volume for each volume specified by the -name or +-file argument, to house the restored data from that volume. +The Backup System derives the new volume's name by appending the +specified string to the read/write base name, and creates a new VLDB volume +entry. It preserves the contents of each existing volume. Any +string other than .readonly or .backup is +acceptable, but the combination of the base name and extension cannot exceed +22 characters in length. To use a period to separate the extension from +the name, specify it as the first character of the string (as in +.rst, for example). +

-portoffset +

Provide this argument unless the default value of 0 (zero) is appropriate +for all dumps. If 0 is just one of the values in the list, +provide it explicitly in the appropriate order. +

-n +

Displays a list of the volumes to be restored if the flag were not +included, without actually restoring them. The Output +section of this reference page details the format of the output. When +combined with the -name argument, its output is easily edited for +use as input to the -file argument on a subsequent backup +volsetrestore command. +

-localauth +

-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 +

If the -n flag is not provided, the command displays a unique +task ID number for the operation, in two places: +

In the shell window, directly following the command line +
In the Tape Coordinator window, if the butc process was started +at debug level 1 +

The task ID number is not the same as the job ID number displayed by the +(backup) jobs command when the (backup) volsetrestore +command is issued in interactive mode. The Backup System does not +assign either type of ID number until the restoration process actually +begins. +

When the -n flag is included, no task ID or job ID numbers are +reported because none are assigned. Instead, the output begins with a +count of the number of volumes to be restored, followed by a line for each +dump of a volume. For each volume, the line representing the most +recent full dump appears first, and lines for any subsequent incremental dumps +follow, ordered by dump level. The lines for a given volume do not +necessarily appear all together, however. +

The format of each line is as follows (the output is shown here on two +lines only for legibility reasons): +

   machine partition volume_dumped  # as volume_restored; tape_name (tape_ID);  \
+              pos position_number; date
+   
+

where +

machine +: Names the file server machine that currently houses the volume, as listed +in the VLDB. +
partition +: Names the partition that currently houses the volume, as listed in the +VLDB. +
volume_dumped +: Specifies the version (read/write or backup) of the volume that was +dumped, as listed in the Backup Database. +
volume_restored +: Specifies the name under which to restore the volume. The Backup +System only restores data to read/write volumes. If the +-extension argument is included, then the specified extension +appears on the name in this field (for example, +user.pat.rst). +
tape_name +: Names the tape containing the dump of the volume, from the Backup +Database. If the tape has a permanent name, it appears here; +otherwise, it is the AFS tape name. +
tape_ID +: The tape ID of the tape containing the dump of the volume, from the Backup +Database. +
position_number +: Specifies the dump's position on the tape (for example, 31 +indicates that 30 volume dumps precede the current one on the tape). If +the dump was written to a backup data file, this number is the ordinal of the +16 KB-offset at which the volume's data begins. +
date +: The date and time when the volume was dumped. +

One way to generate a file for use as input to the -file +argument is to combine the -name and -n options, +directing the output to a file. The IBM AFS Administration +Guide section on using the Backup System to restore data explains how to +edit the file as necessary before using it as input to the -file +argument. +

The output of this command includes only volumes for which the Backup +Database includes at least one dump record. The command interpreter +generates a message on the standard error stream about volumes that do not +have dump records but either are listed in the file named by the +-file argument, or appear in the VLDB as a match to a volume entry +in the volume set named by the -name argument. +

Examples +

The following command restores all volumes included in entries in the +volume set named data.restore, which was created expressly +to restore data to a pair of file server machines on which all data was +corrupted due to a software error. All volumes are restored to the +sites recorded in their entries in the VLDB. +

   % backup volsetrestore -name data.restore
+   Starting restore
+   backup: task ID of restore operation: 112
+   backup: Finished doing restore
+   
+

The following command restores all volumes that have entries in the file +named /tmp/restore: +

   % backup volsetrestore -file /tmp/restore
+   Starting restore
+   backup: task ID of restore operation: 113
+   backup: Finished doing restore
+   
+

The /tmp/restore file has the following contents: +

   fs1.abc.com b user.pat
+   fs1.abc.com b user.terry
+   fs1.abc.com b user.smith
+   fs2.abc.com c user.jones
+          .         .     .
+          .         .     .
+   
+

Privilege Required +

Related Information +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf093.htm b/doc/html/AdminReference/auarf093.htm new file mode 100644 index 0000000..8d596d7 --- /dev/null +++ b/doc/html/AdminReference/auarf093.htm @@ -0,0 +1,254 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos

+ + + + + + + +

Purpose +

Introduction to the bos command suite +

Description +

The commands in the bos command suite are the administrative +interface to the Basic OverSeer (BOS) Server, which runs on every file server +machine to monitor the other server processes on it. If a process +fails, the BOS Server can restart it automatically, taking into account +interdependencies between it and other processes. The BOS Server frees +system administrators from constantly monitoring the status of server machines +and processes. +

There are several categories of commands in the bos command +suite: +

Commands to administer server process binary files: bos +getdate, bos install, bos prune, and bos +uninstall +
Commands to maintain system configuration files: bos +addhost, bos addkey, bos adduser, bos +listhosts, bos listkeys, bos listusers, bos +removehost, bos removekey, bos removeuser, and +bos setcellname +
Commands to start and stop processes: bos create, +bos delete, bos restart, bos shutdown, +bos start, bos startup, and bos stop +
Commands to set and verify server process and server machine status: +bos getlog, bos getrestart, bos setauth, +bos setrestart, and bos status +
A command to restore file system consistency: bos salvage +
Commands to obtain help: bos apropos and bos +help +

The BOS Server and the bos commands use and maintain the +following configuration and log files: +

The /usr/afs/etc/CellServDB file lists the local cell's +database server machines. These machines run the Authentication, +Backup, Protection and Volume Location (VL) Server processes, which maintain +databases of administrative information. The database server processes +consult the file to learn about their peers, whereas the other server +processes consult it to learn where to access database information as +needed. To administer the CellServDB file, use the following +commands: bos addhost, bos listhosts, bos +removehost, and bos setcellname. +
The /usr/afs/etc/KeyFile file lists the server encryption keys +that the server processes use to decrypt tickets presented by client processes +and one another. To administer the KeyFile file, use the +following commands: bos addkey, bos listkeys, and +bos removekey. +
The /usr/afs/etc/ThisCell file defines the cell to which the +server machine belongs for the purposes of server-to-server +communication. Administer it with the bos setcellname +command. There is also a /usr/vice/etc/ThisCell file that +defines the machine's cell membership with respect to the AFS command +suites and Cache Manager access to AFS data. +
The /usr/afs/etc/UserList file lists the user name of each +administrator authorized to issue privileged bos and vos +commands. To administer the UserList file, use the following +commands: bos adduser, bos listusers, and bos +removeuser. +
The /usr/afs/local/BosConfig file defines which AFS server +processes run on the server machine, and whether the BOS Server restarts them +automatically if they fail. It also defines when all processes restart +automatically (by default once per week), and when the BOS Server restarts +processes that have new binary files (by default once per day). To +administer the BosConfig file, use the following commands: +bos create, bos delete, bos getrestart, +bos setrestart, bos start, and bos +stop. +
The /usr/afs/log/BosLog file records important operations the +BOS Server performs and error conditions it encounters. +

For more details, see the reference page for each file. +

Options +

The following arguments and flags are available on many commands in the +bos suite. The reference page for each command also lists +them, but they are described here in greater detail. + + + +

-cell <cell name> +

The value of the AFSCELL environment variable +
The local /usr/vice/etc/ThisCell file +

-help +

+ +-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 bos command interpreter presents the ticket, which +never expires, to the BOS Server during mutual authentication. +

+ +-noauth +

Establishes an unauthenticated connection to the BOS Server, in which the +BOS Server treats the issuer as the unprivileged user +anonymous. It is useful only when authorization checking is +disabled on the server machine (during the installation of a file server +machine or when the bos setauth command has been used during other +unusual circumstances). In normal circumstances, the BOS Server allows +only privileged users to issue commands that change the status of a server or +configuration file, and refuses to perform such an action even if the +-noauth flag is provided. Do not combine the +-noauth and -localauth flags. +

-server <machine name> + +

Indicates the AFS server machine on which to run the command. +Identify the machine by its IP address in dotted decimal format, its +fully-qualified host name (for example, fs1.abc.com), +or by an abbreviated form of its host name that distinguishes it from other +machines. Successful use of an abbreviated form depends on the +availability of a name service (such as the Domain Name Service or a local +host table) at the time the command is issued. +

For the commands that alter the administrative files shared by all server +machines in the cell (the bos addhost, bos addkey, +bos adduser, bos removehost, bos removekey, +and bos removeuser commands), the appropriate machine depends on +whether the cell uses the United States or international version of AFS: +

If the cell runs the United States edition of AFS and (as recommended) +uses the Update Server to distribute the contents of the +/usr/afs/etc directory, provide the name of the system control +machine. After issuing the command, allow up to five minutes for the +Update Server to distribute the changed file to the other AFS server machines +in the cell. If the specified machine is not the system control machine +but is running an upclientetc process that refers to the system +control machine, then the change will be overwritten when the process next +brings over the relevant file from the system control machine. +
If the cell runs the international edition of AFS, do not use the Update +Server to distribute the contents of the /usr/afs/etc +directory. Instead, repeatedly issue the command, naming each of the +cell's server machines in turn. To avoid possible inconsistency +problems, finish issuing the commands within a fairly short time. +

Privilege Required + + +

To issue any bos command that changes a configuration file or +alters process status, the issuer must be listed in the +/usr/afs/etc/UserList file on the server machine named by the +-server argument. Alternatively, if the +-localauth flag is included the issuer must be logged on as the +local superuser root. +

To issue a bos command that only displays information (other +than the bos listkeys command), no privilege is required. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf094.htm b/doc/html/AdminReference/auarf094.htm new file mode 100644 index 0000000..19053b4 --- /dev/null +++ b/doc/html/AdminReference/auarf094.htm @@ -0,0 +1,124 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos addhost

+ + + + + +

Purpose +

Adds a database server machine to the /usr/afs/etc/CellServDB +file +

Synopsis +

bos addhost -server <machine name>  -host <host name>⁺
+            [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+    
+bos addh -s <machine name>  -ho <host name>⁺
+         [-c <cell name>]  [-n]  [-l]  [-he]
+

Description +

The bos addhost command adds an entry for each database server +machine specified with the -host argument to the +/usr/afs/etc/CellServDB file on the machine named by the +-server argument. +

Cautions +

After executing this command (and waiting for the Update Server to +propagate the changes, if it is used), restart the database server processes +on all database server machines to force election of a quorum that includes +the new set of machines listed in the /usr/afs/etc/CellServDB +file. The IBM AFS Quick Beginnings explains in more detail +how to add and remove database server machines. +

It is best to maintain a one-to-one mapping between hostnames and IP +addresses on a multihomed database server machine (this is actually the +conventional configuration for any AFS machine). The BOS Server uses +the gethostbyname( ) routine to obtain the IP address +associated with the hostname specified by the -host +argument. If there is more than one address, the BOS Server records in +the CellServDB entry the one that appears first in the list of +addresses returned by the routine. The routine possibly returns +addresses in a different order on different machines, which can create +inconsistency. +

Options +

-server +

Identifies the server machine on which to change the +/usr/afs/etc/CellServDB file. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference page for +the bos command suite. +

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 conventional to specify only the system control machine as a value for the +-server argument. In cells that run the international +version of AFS, repeat the command for each file server machine. For +further discussion, see the introductory reference page for the bos +command suite. +

-host +

Specifies the fully-qualified host name (such as +db1.abc.com) of each database server machine to +register in the CellServDB file. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command adds the database server machines +db2.abc.com and db3.abc.com +to the /usr/afs/etc/CellServDB file on the machine +fs1.abc.com (the system control machine). +

   % bos addhost -server fs1.abc.com -host db2.abc.com db3.abc.com
+   
+

Privilege Required +

The issuer must be listed in the /usr/afs/etc/UserList file on +the machine named by the -server argument, or must be logged onto a +server machine as the local superuser root if the +-localauth flag is included. +

Related Information +

bos +

bos listhosts +

bos removehost +

IBM AFS Quick Beginnings +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf095.htm b/doc/html/AdminReference/auarf095.htm new file mode 100644 index 0000000..8b07eba --- /dev/null +++ b/doc/html/AdminReference/auarf095.htm @@ -0,0 +1,144 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos addkey

+ + + + + + + + + +

Purpose +

Adds a new server encryption key to the /usr/afs/etc/KeyFile +file +

Synopsis +

bos addkey -server <machine name>  [-key <key>]
+           -kvno <key version number>  [-cell <cell name>]
+           [-noauth]  [-localauth]  [-help]
+    
+bos addk -s <machine name>  [-ke <key>]  -kv <key version number>
+         [-ce <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos addkey command constructs a server encryption key from +the text string provided, assigns it the key version number specified with the +-kvno argument, and adds it to the /usr/afs/etc/KeyFile +file on the machine specified with the -server argument. Be +sure to use the kas setpassword or kas setkey command to +add the same key to the afs entry in the Authentication +Database. +

Do not use the -key argument, which echoes the password string +visibly on the screen. If the argument is omitted, the BOS Server +prompts for the string and does not echo it visibly: +

   Input key:
+   Retype input key:
+   
+

The BOS Server prohibits reuse of any key version number already listed in +the /usr/afs/etc/KeyFile file. This ensures that users who +still have tickets sealed with the current key are not prevented from +communicating with a server process because the current key is overwritten +with a new key. Use the bos listkeys command to display the +key version numbers in the /usr/afs/etc/KeyFile file. +

Options +

-server +

Indicates the server machine on which to change the +/usr/afs/etc/KeyFile file. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference page for +the bos command suite. +

-key +

Specifies a character string just like a password; the BOS Server +calls a DES conversion function to encode it into a form appropriate for use +as an encryption key. Omit this argument to have the BOS Server prompt +for the string instead. +

-kvno +

Defines the new key's key version number. It must be an +integer in the range from 0 (zero) through 255. +For the sake of simplicity, use the number one higher than the current highest +key version number; use the bos listkeys command to display +key version numbers. + +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

If the strings typed at the Input key and Retype input +key prompts do not match, the following message appears, and the command +exits without adding a new key: +

   Input key mismatch
+   
+

Examples +

The following command adds a new server encryption key with key version +number 14 to the KeyFile file kept on the machine +fs1.abc.com (the system control machine). The +issuer omits the -key argument, as recommended, and provides the +password at the prompts. +

   % bos addkey -server fs1.abc.com -kvno 14
+   Input key:
+   Retype input key:
+   
+

Privilege Required +

Related Information +

bos +

bos listkeys +

bos removekey +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf096.htm b/doc/html/AdminReference/auarf096.htm new file mode 100644 index 0000000..b55291d --- /dev/null +++ b/doc/html/AdminReference/auarf096.htm @@ -0,0 +1,105 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos adduser

+ + + + + + + +

Purpose +

Adds a privileged user to the /usr/afs/etc/UserList file +

Synopsis +

bos adduser -server <machine name>  -user <user names>⁺
+            [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+     
+bos addu -s <machine name>  -u <user names>⁺
+         [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos adduser command adds each user name specified with the +-user argument to the /usr/afs/etc/UserList file on the +machine named by the -server argument. It is the +issuer's responsibility to verify that an entry for the user exists in +the Authentication and Protection Databases. +

Options +

-server +

Indicates the server machine on which to change the +/usr/afs/etc/UserList file. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference page for +the bos command suite. +

-user +

Specifies each user name to insert into the +/usr/afs/etc/UserList file. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command adds the user names pat and +smith to the /usr/afs/etc/UserList file on the machine +fs1.abc.com (the system control machine). +

   % bos adduser -server fs1.abc.com -user pat smith
+   
+

Privilege Required +

Related Information +

bos +

bos listusers +

bos removeuser +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf097.htm b/doc/html/AdminReference/auarf097.htm new file mode 100644 index 0000000..be8ad06 --- /dev/null +++ b/doc/html/AdminReference/auarf097.htm @@ -0,0 +1,73 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos apropos

+ + + + +

Purpose +

Displays each help entry containing a keyword string +

Synopsis +

bos apropos -topic <help string>  [-help]
+    
+bos ap -t <help string>  [-h]
+

Description +

The bos apropos command displays the first line of the online +help entry for any bos 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 bos 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 +bos command where the string specified with the -topic +argument is part of the command name or first line. +

Examples +

The following command lists all bos commands that include the +word restart in their names or short descriptions: +

   % bos apropos restart
+   getrestart: get restart times
+   restart: restart all processes
+   setrestart: set restart times
+   
+

Privilege Required +

None +

Related Information +

bos +

bos help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf098.htm b/doc/html/AdminReference/auarf098.htm new file mode 100644 index 0000000..bbb2048 --- /dev/null +++ b/doc/html/AdminReference/auarf098.htm @@ -0,0 +1,367 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos create

+ + + + + + + + + + +

Purpose +

Defines a new process in the /usr/afs/local/BosConfig file and +starts it running +

Synopsis +

bos create -server <machine name>  -instance <server process name>
+           -type <server type>  -cmd <command lines>⁺
+           [-notifier <Notifier program>]  [-cell <cell name>]
+           [-noauth]  [-localauth]  [-help]
+   
+bos c -s <machine name>  -i <server process name>  -t <server type>
+      -cm <command lines>⁺  [-not <Notifier program>]  [-ce <cell name>]
+      [-noa]  [-l]  [-h]
+

Description +

The bos create command creates a server process entry in the +/usr/afs/local/BosConfig file on the server machine named by the +-server argument, sets the process's status to Run +in the BosConfig file and in memory, and starts the process. +

A server process's entry in the BosConfig file defines its +name, its type, the command that initializes it, and optionally, the name of a +notifier program that runs when the process terminates. +

Options +

-server +

Indicates the server machine on which to define and start the new +process. Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see the +introductory reference page for the bos command suite. +

-instance +

Names the process to define and start. Any name is acceptable, but +for the sake of simplicity it is best to use the last element of the +process's binary file pathname, and to use the same name on every server +machine. The conventional names, as used in all AFS documentation, +are: +

buserver +: The Backup Server process + + +
fs +: The process that combines the File Server, Volume Server, and Salvager +processes (fileserver, volserver, and +salvager) + + +
kaserver +: The Authentication Server process + + +
ptserver +: The Protection Server process + + +
runntp +: The controller process for the Network Time Protocol Daemon + + +
upclientbin +: The client portion of the Update Server process that retrieves binary +files from the /usr/afs/bin directory of the binary distribution +machine for this machine's CPU/operating system type. (The name of +the binary is upclient, but the bin suffix distinguishes +this process from upclientetc.) + + +
upclientetc +: The client portion of the Update Server process that retrieves +configuration files from the /usr/afs/etc directory of the system +control machine. Do not run this process in cells that use the +international edition of AFS. (The name of the binary is +upclient, but the etc suffix distinguishes this process +from upclientbin.) +
upserver +: The server portion of the Update Server process + + +
vlserver +: The Volume Location (VL) Server process + + +

-type +

Specifies the process's type. The acceptable values are: +

cron +: Use this value for cron-type processes that the BOS Server starts only at +a defined daily or weekly time, rather than whenever it detects that the +process has terminated. AFS does not define any such processes by +default, but makes this value available for administrator use. Define +the time for command execution as part of the -cmd argument to the +bos create command. +
fs +: Use this value only for the fs process, which combines the File +Server, Volume Server and Salvager processes. If one of the component +processes terminates, the BOS Server shuts down and restarts the processes in +the appropriate order. +
simple +: Use this value for all processes listed as acceptable values to the +-instance argument, except for the fs process. +There are no interdependencies between simple processes, so the BOS Server can +stop and start them independently as necessary. +

-cmd +

Specifies each command the BOS Server runs to start the process. +Specify no more than six commands (which can include the command's +options, in which case the entire string is surrounded by double quotes); +any additional commands are ignored. +

For a simple process, provide the complete pathname of the process's +binary file on the local disk (for example, /usr/afs/bin/ptserver +for the Protection Server). If including any of the initialization +command's options, surround the entire command in double quotes (" +"). The upclient process has a required argument, and +the commands for all other processes take optional arguments. + +

For the fs process, provide the complete pathname of the local +disk binary file for each of the component processes: +fileserver, volserver, and salvager, in that +order. The standard binary directory is /usr/afs/bin. +If including any of an initialization command's options, surround the +entire command in double quotes (" "). + +

For a cron process, provide two parameters: + +

The complete local disk pathname of either an executable file or a command +from one of the AFS suites (complete with all of the necessary +arguments). Surround this parameter with double quotes (" ") +if it contains spaces. +
A specification of when the BOS Server executes the file or command +indicated by the first parameter. There are three acceptable +values: +
- The string now, which directs the BOS Server to execute the +file or command immediately and only once. It is usually simpler to +issue the command directly or issue the bos exec command. +
- A time of day. The BOS Server executes the file or command daily at +the indicated time. Separate the hours and minutes with a colon +(hh:MM), and use either 24-hour format, or a value +in the range from 1:00 through 12:59 with +the addition of am or pm. For example, both +14:30 and "2:30 pm" indicate 2:30 in +the afternoon. Surround this parameter with double quotes (" +") if it contains a space. +
- A day of the week and time of day, separated by a space and surrounded +with double quotes (" "). The BOS Server executes the file +or command weekly at the indicated day and time. For the day, provide +either the whole name or the first three letters, all in lowercase letters +(sunday or sun, thursday or thu, +and so on). For the time, use the same format as when specifying the +time alone. +
+

-notifier +

Specifies the complete pathname on the local disk of a program that the +BOS Server invokes when the process terminates. The AFS distribution +does not include any notifier programs, but this argument is available for +administrator use. See the Related Information +section. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command defines and starts the simple process +kaserver on the machine fs3.abc.com: +

   % bos create -server fs3.abc.com -instance kaserver -type simple  \              
+                -cmd /usr/afs/bin/kaserver
+   
+

The following command defines and starts the simple process +upclientbin on the machine +fs4.abc.com. It references +fs1.abc.com as the source for updates to binary +files, checking for changes to the /usr/afs/bin directory every 120 +seconds. +

   % bos create -server fs4.abc.com -instance upclientbin -type simple  \
+                -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120  \
+                /usr/afs/bin"
+   
+

The following command creates the fs process fs on the machine +fs4.abc.com. Type the command on a single +line. +

   % bos create -server fs4.abc.com -instance fs -type fs  \
+                -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver  \
+                /usr/afs/bin/salvager
+   
+

The following command creates a cron process called +userbackup on the machine fs5.abc.com, so +that the BOS Server issues the indicated vos backupsys command each +day at 3:00 a.m. (the command creates a backup version of +every volume in the file system whose name begins with +user). Note that the issuer provides the complete pathname +to the vos command, includes the -localauth flag on it, +and types the entire bos create command on one line. +

   % bos create -server fs5.abc.com -instance userbackup -type cron  \      
+                -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
+   
+

Privilege Required +

Related Information +

If the -notifier argument is included when this command is used +to define and start a process, the BOS Server invokes the indicated +notifier program when the process exits. The intended use of +a notifier program is to inform administrators when a process exits +unexpectedly, but it can be used to perform any appropriate actions. +The following paragraphs describe the bnode and +bnode_proc structures in which the BOS Server records information +about the exiting process. The list of AFS commands related to this one +follows. +

The BOS Server constructs and sends on the standard output stream one +bnode and one bnode_proc structure for each exiting +process associated with the notifier program. It brackets each +structure with appropriate BEGIN and END statements +(BEGIN bnode and END bnode, BEGIN bnode_proc +and END bnode_proc), which immediately follow the preceding newline +character with no intervening spaces or other characters. If the +notifier program does not need information from a structure, it can scan ahead +in the input stream for the END statement. +

In general, each field in a structure is a string of ASCII text terminated +by the newline character. The format of the information within a +structure possibly varies slightly depending on the type of process associated +with the notifier program. +

The C code for the bnode and bnode_proc structures +follows. Note that the structures sent by the BOS Server do not +necessarily include all of the fields described here, because some are used +only for internal record keeping. The notifier process must robustly +handle the absence of expected fields, as well as the presence of unexpected +fields, on the standard input stream. +

For proper performance, the notifier program must continue processing the +input stream until it detects the end-of-file (EOF). The BOS Server +closes the standard input file descriptor to the notifier process when it has +completed delivery of the data, and it is the responsibility of the notifier +process to terminate properly. +

struct bnode contents +

   struct bnode {
+      struct bnode *next;      /* next pointer in top-level's list */
+      char *name;              /* instance name */
+      long nextTimeout;        /* next time this guy should be awakened */
+      long period;             /* period between calls */
+      long rsTime;             /* time we started counting restarts */
+      long rsCount;            /* count of restarts since rsTime */
+      struct bnode_type *type; /* type object */
+      struct bnode_ops *ops;   /* functions implementing bnode class */
+      long procStartTime;      /* last time a process was started */
+      long procStarts;         /* number of process starts */
+      long lastAnyExit;        /* last time a process exited for any reason */
+      long lastErrorExit;      /* last time a process exited unexpectedly */
+      long errorCode;          /* last exit return code */
+      long errorSignal;        /* last proc terminating signal */
+      char *lastErrorName;     /* name of proc that failed last */
+      short refCount;          /* reference count */
+      short flags;             /* random flags */
+      char goal;               /* 1=running or 0=not running */
+      char fileGoal;           /* same, but to be stored in file */
+};
+   
+

format of struct bnode explosion +

   printf("name: %s\n",tp->name);
+   printf("rsTime: %ld\n", tp->rsTime);
+   printf("rsCount: %ld\n", tp->rsCount);
+   printf("procStartTime: %ld\n", tp->procStartTime);
+   printf("procStarts: %ld\n", tp->procStarts);
+   printf("lastAnyExit: %ld\n", tp->lastAnyExit);
+   printf("lastErrorExit: %ld\n", tp->lastErrorExit);
+   printf("errorCode: %ld\n", tp->errorCode);
+   printf("errorSignal: %ld\n", tp->errorSignal);
+   printf("lastErrorName: %s\n", tp->lastErrorName);
+   printf("goal: %d\n", tp->goal);
+   
+

struct bnode_proc contents +

   struct bnode_proc {
+      struct bnode_proc *next; /* next guy in top-level's list */
+      struct bnode *bnode;     /* bnode creating this process */
+      char *comLine;           /* command line used to start this process */
+      char *coreName;          /* optional core file component name */
+      long pid;                /* pid if created */
+      long lastExit;           /* last termination code */
+      long lastSignal;         /* last signal that killed this guy */
+      long flags;              /* flags giving process state */
+};
+   
+

format of struct bnode_proc explosion +

   printf("comLine: %s\n", tp->comLine);
+   printf("coreName: %s\n", tp->coreName);
+   printf("pid: %ld\n", tp->pid);
+   printf("lastExit: %ld\n", tp->lastExit);
+   printf("lastSignal: %ld\n", tp->lastSignal);
+   
+

bos +

runntp +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf099.htm b/doc/html/AdminReference/auarf099.htm new file mode 100644 index 0000000..956055d --- /dev/null +++ b/doc/html/AdminReference/auarf099.htm @@ -0,0 +1,103 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos delete

+ + + + + +

Purpose +

Deletes a server process from the /usr/afs/local/BosConfig file +

Synopsis +

bos delete -server <machine name>  -instance <server process name>⁺
+           [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+    
+bos d -s <machine name>  -i <server process name>⁺  [-c <cell name>]  
+      [-n]  [-l]  [-h]
+

Description +

The bos delete command removes the +/usr/afs/local/BosConfig entry for each process indicated by the +-instance argument, on the server machine named by the +-server argument. +

Before issuing this command, issue the bos stop command to stop +the process and set its status flag in the BosConfig file to +NotRun. The bos delete command fails with an +error message if a process's status flag is Run. +

Options +

-server +: Indicates the server machine on which to delete the server process entry +from the /usr/afs/local/BosConfig file. Identify the machine +by IP address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference page for +the bos command suite. +
-instance +: Names each process to delete. Use the name assigned with the +-instance argument to the bos create command; +process names appear in the output of the bos status +command. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command removes the buserver, kaserver, +ptserver, and vlserver entries from the +BosConfig file on db3.abc.com, a database +server machine being decommissioned. +

   % bos delete -server db3.abc.com -instance buserver kaserver ptserver vlserver
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf100.htm b/doc/html/AdminReference/auarf100.htm new file mode 100644 index 0000000..aee75e6 --- /dev/null +++ b/doc/html/AdminReference/auarf100.htm @@ -0,0 +1,91 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos exec

+ + + + + +

Purpose +

Executes a command on a remote server machine +

Synopsis +

bos exec -server <machine name>  -cmd <command to execute>
+         [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+   
+bos e -s <machine name>  -cm <command to execute>  [-ce <cell name>]    
+      [-n]  [-l]  [-h]
+

Description +

The bos exec command executes the indicated command on the file +server machine named by the -server argument. Its intended +use is to reboot the machine, using the /etc/reboot command or +equivalent. +

Options +

-server +: Indicates the server machine on which to execute the command. +Identify the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +
-cmd +: Specifies the complete local disk pathname of the command to execute (for +example, /etc/reboot). Surround this argument with double +quotes ("") if the command contains one or more spaces. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command reboots the machine +fs2.abc.com. The issuer has previously issued +the bos shutdown command to shutdown all processes cleanly. +

   % bos exec -server fs2.abc.com -cmd /sbin/shutdown -r now
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf101.htm b/doc/html/AdminReference/auarf101.htm new file mode 100644 index 0000000..1c4cb28 --- /dev/null +++ b/doc/html/AdminReference/auarf101.htm @@ -0,0 +1,120 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos getdate

+ + + + + + + + + + + +

Purpose +

Displays the time stamps on an AFS binary file +

Synopsis +

bos getdate -server <machine name>  -file <files to check>⁺
+            [-dir <destination dir>]  [-cell <cell name>]
+            [-noauth]  [-localauth]  [-help]
+    
+bos getd -s <machine name>  -f <files to check>⁺  [-d <destination dir>]
+         [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos getdate command displays the time stamps on the current +version, .BAK version (if any) and .OLD +version (if any) of each binary file named by the -file +argument. (The BOS Server automatically creates .BAK +and .OLD versions when new binaries are installed with the +bos install command.) The files must reside in the +/usr/afs/bin directory on the server machine named by the +-server argument unless the -dir argument indicates an +alternate directory. +

To revert to the .BAK version of a binary, use the +bos uninstall command. To remove obsolete binary files from +the /usr/afs/bin directory, use the bos prune +command. +

Options +

-server +

Indicates the server machine from which to list binary files. +Identify the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +

All server machines of the same AFS system type show the same timestamps if +the binaries were installed properly on the binary distribution machine for +this machine's system type, and if all other machines of that type are +running the appropriate upclientbin process. +

-file +

Names each binary file to list. +

-dir +

Specifies the complete pathname of the local disk directory containing +each file named by the -file argument. It is necessary only +if the files are not in the /usr/afs/bin directory. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

For each file specified with the -file argument, the output +displays the time stamp on the current (unmarked), .BAK, and +.OLD version. The output explicitly reports that a +version does not exist, rather than simply omitting it. +

Examples +

The following command examines the time stamps on the files with basename +kaserver on the machine fs2.abc.com: +

   % bos getdate -server fs2.abc.com -file kaserver
+   File /usr/afs/bin/kaserver dated Mon Jan 4 10:00:36 1999.
+   .BAK file dated Wed Dec 9 18:55:04 1998, no .OLD file.
+   
+

Privilege Required +

None +

Related Information +

bos +

bos install +

bos prune +

bos uninstall +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf102.htm b/doc/html/AdminReference/auarf102.htm new file mode 100644 index 0000000..3be3b28 --- /dev/null +++ b/doc/html/AdminReference/auarf102.htm @@ -0,0 +1,136 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos getlog

+ + + + + + + + + +

Purpose +

Prints a server process's log file +

Synopsis +

bos getlog -server <machine name>  -file <log file to examine>
+           [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+   
+bos getl -s <machine name>  -f <log file to examine>  [-c <cell name>]     
+         [-n]  [-l]  [-h]
+

Description +

The bos getlog command displays on the standard output stream +the specified log file from the machine named by the -server +argument. The BOS Server fetches the log file from the +/usr/afs/logs directory unless an alternate pathname is provided as +part of the -file argument. +

Cautions +

Log files can grow quite large, especially for the database server +processes. To keep them to a manageable size, periodically either use +the UNIX rm command to truncate each log file, or use the bos +restart command to restart each process. +

It can take up to five minutes after the file is removed or process +restarted for the space occupied by a log file to become available. +

Options +

-server +

Indicates the server machine from which to retrieve the log file. +Identify the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +

-file +

Names the log file to display. If a filename only is provided, the +BOS Server fetches the log file from the /usr/afs/logs +directory; the standard values are: +

AuthLog +: The Authentication Server (kaserver) log file +
BackupLog +: The Backup Server (buserver) log file +
BosLog +: The BOS Server (bosserver) log file +
FileLog +: The File Server (fileserver) log file +
SalvageLog +: The Salvager (salvager) log file +
VLLog +: The Volume Location (VL) Server (vlserver) log file +
VolserLog +: The Volume Server (volserver) log file +

If a pathname and filename are provided, the log file is retrieved from the +indicated directory. Partial pathnames are interpreted relative to the +/usr/afs/logs directory. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The output is preceded by the line +

   Fetching log file 'filename'...
+   
+

The remainder of the output depends on the particular log file. +

Examples +

The following example displays the FileLog file from the machine +fs3.abc.com: +

   % bos getlog -server fs3.abc.com -file FileLog
+   Fetching log file 'FileLog'...
+   Sun Nov 8 04:00:34 1998 File server starting
+   Sun Nov 8 04:00:39 1998 Partition /vicepa:  attached 21 volumes; 
+                           0 volumes not attached
+   Sun Nov 8 04:00:40 1998 File Server started Sun Nov 8 04:00:40 
+                           1998
+   Mon Nov 9 21:45:06 1998 CB: RCallBack (zero fid probe in host.c) 
+                           failed for host 28cf37c0.22811
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf103.htm b/doc/html/AdminReference/auarf103.htm new file mode 100644 index 0000000..05448d4 --- /dev/null +++ b/doc/html/AdminReference/auarf103.htm @@ -0,0 +1,134 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos getrestart

+ + + + + + + + + +

Purpose +

Displays the automatic restart times for server processes +

Synopsis +

bos getrestart -server <machine name>  [-cell <cell name>]  
+               [-noauth]  [-localauth]  [-help]
+   
+bos getr -s <machine name>  [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos getrestart command displays two restart times from the +/usr/afs/local/BosConfig file on the server machine named by the +-server argument: +

The general restart time at which the BOS Server process +automatically restarts itself and all processes marked with status +Run in the BosConfig file. The default is Sunday +at 4:00 a.m. +
The binary restart time at which the BOS Server automatically +restarts any 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. Use the bos +getdate command to list a binary file's timestamp, and the +-long flag to the bos status command to display a +process's most recent restart time. +

Use the bos setrestart command to set the restart times. +

Options +

-server +: Indicates the server machine for which to display the restart +times. Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see the +introductory reference page for the bos command suite. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output consists of two lines: +

   Server machine_name restarts at time
+   Server machine_name restarts for new binaries at time
+   
+

Possible values for time include: +

never, indicating that the BOS Server never performs that type +of restart +
now, indicating that the BOS Server performs that type of +restart only each time it restarts +
A specified day and time, indicating that the BOS Server performs that +type of restart once per week. Example: sun 4:00 +am. +
A specified time, indicating that the BOS Server performs that type of +restart once per day. Examples: 11:00 pm, +3:00 am. +

Examples +

The following example displays the restart times for the machine +db2.abc.com: +

   % bos getrestart db2.abc.com
+   Server db2.abc.com restarts at sun 4:00 am
+   Server db2.abc.com restarts for new binaries at 2:15 am
+   
+

In the following example, the issuer abbreviates the machine name +fs1.abc.com to fs1, relying on the +cell's name server to resolve the name. The output echoes the +abbreviated form. +

   % bos getrestart fs1
+   Server fs1 restarts at sat 5:00 am
+   Server fs1 restarts for new binaries at 11:30 pm
+   
+

Privilege Required +

None +

Related Information +

bos +

bos getdate +

bos setrestart +

bos status +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf104.htm b/doc/html/AdminReference/auarf104.htm new file mode 100644 index 0000000..9d4426a --- /dev/null +++ b/doc/html/AdminReference/auarf104.htm @@ -0,0 +1,85 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos help

+ + + +

Purpose +

Displays the syntax of specified bos commands or lists +functional descriptions of all bos commands +

Synopsis +

bos help [-topic <help string>⁺]  [-help]
+     
+bos h [-t <help string>⁺]  [-h]
+

Description +

The bos help command displays the complete online help entry +(short description and syntax statement) for each command operation code +specified by the -topic argument. If the -topic +argument is omitted, the output includes the first line (name and short +description) of the online help entry for every bos command. +

To list every bos command whose name or short description +includes a specified keyword, use the bos apropos command. +

Options +

-topic +: Indicates each command for which to display the complete online help +entry. Omit the bos part of the command name, providing only +the operation code (for example, specify status, not bos +status). If this argument is omitted, the output briefly +describes every bos command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each bos command consists of the +following two or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following command displays the online help entry for the bos +status command: +

   % bos help status
+   bos status: show server instance status 
+   Usage: bos status -server <machine name> [-instance <server
+   process name>+] [-long] [-cell <cell name>] [-noauth] 
+   [-localauth] [-help]
+   
+

Privilege Required +

None +

Related Information +

bos +

bos apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf105.htm b/doc/html/AdminReference/auarf105.htm new file mode 100644 index 0000000..aae3c4f --- /dev/null +++ b/doc/html/AdminReference/auarf105.htm @@ -0,0 +1,137 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos install

+ + + + + + + + +

Purpose +

Installs a new version of a binary file +

Synopsis +

bos install -server <machine name>  -file <files to install>⁺
+            [-dir <destination dir>]  [-cell <cell name>]  
+            [-noauth]  [-localauth]  [-help]
+    
+bos i -s <machine name>  -f <files to install>⁺
+      [-d <destination dir>]  [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos install command copies each binary file specified with +the -file argument to the local disk of the server machine named by +the -server argument, which is normally the binary distribution +machine for its CPU/operating system type. The destination directory is +/usr/afs/bin unless the -dir argument indicates an +alternate directory. The source file's UNIX mode bits are +preserved in the transfer. +

If there is already a file of the same name in the destination directory, +the BOS Server automatically saves it by adding a .BAK +extension. If there is a current .BAK version at +least seven days old, it replaces the current .OLD +version. If there is no current .OLD version, the +current .BAK version becomes the .OLD +version automatically. The bos getdate command displays the +timestamps on the current versions of the file. +

To start using the new binary immediately, issue the bos restart +command. Otherwise, the BOS Server automatically restarts the process +at the time defined in the /usr/afs/local/BosConfig file; use +the bos getrestart command to display the time and the bos +setrestart time to set it. +

Options +

-server +

Indicates the binary distribution machine on which to install the new +binaries. Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see the +introductory reference page for the bos command suite. +

If the machine is not a binary distribution machine and is running an +upclientbin process, then the files are overwritten the next time +the upclientbin process fetches the corresponding file from the +distribution machine (by default within five minutes). +

-file +

Specifies the complete pathname of each binary file to copy into the +destination directory. Each source directory can be on the local disk +or in AFS, in which case the issuer of the bos install command must +have the necessary AFS access rights and the local machine must run the Cache +Manager. For the BOS Server to create .BAK and +.OLD versions, the last element in the pathname (the +filename) must match the name of a file in the destination directory. +The reference page for the bos create command lists the standard +binary file names. +

-dir +

Provides the complete pathname of the local disk directory in which to +install binary files. It is necessary only if the destination directory +is not /usr/afs/bin. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command copies the file +/afs/abc.com/rs_aix42/usr/afs/bin/vlserver to the file +/usr/afs/bin/vlserver on the machine +fs3.abc.com, which is the binary distribution machine +for server machines running AIX 4.2 in the abc.com +cell. The current version of the /usr/afs/bin/vlserver file +is moved to /usr/afs/bin/vlserver.BAK. +

   % bos install -server fs3.abc.com    \     
+                 -file /afs/abc.com/rs_aix42/usr/afs/bin/vlserver
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf106.htm b/doc/html/AdminReference/auarf106.htm new file mode 100644 index 0000000..0d866bb --- /dev/null +++ b/doc/html/AdminReference/auarf106.htm @@ -0,0 +1,112 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos listhosts

+ + + + + + + +

Purpose +

Displays the contents of the /usr/afs/etc/CellServDB file +

Synopsis +

bos listhosts -server <machine name>  [-cell <cell name>]  
+              [-noauth]  [-localauth]  [-help]
+    
+bos listh -s <machine name>  [-c <cell name>]  [-n]  [-l]  [-h]
+   
+bos getcell -server <machine name>  [-cell <cell name>]  
+            [-noauth]  [-localauth]  [-help]
+    
+bos getc -s <machine name>  [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos listhosts command formats and displays the list of a +cell's database server machines from the +/usr/afs/etc/CellServDB file on the server machine named by the +-server argument. +

To alter the list of machines, use the bos addhost and bos +removehost commands. +

Options +

-server +

Indicates the server machine from which to display the +/usr/afs/etc/CellServDB file. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference page for +the bos command suite. +

For consistent performance in the cell, the output must be the same on +every server machine. The bos addhost reference page +explains how to keep the machines synchronized. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The first line of the output names the cell to which the server machine +belongs. Each of the following lines names a database server machine +for that cell. +

The Host number assigned to each database server machine is for +server-internal use only and is not the same as, nor necessarily related to, +the machine's IP address. The BOS Server assigned it as part of +performing the bos addhost command. +

Examples +

The following command displays the database server machines listed in the +/usr/afs/etc/CellServDB file on the machine +fs7.abc.com. +

   % bos listhosts fs7.abc.com
+   Cell name is abc.com
+       Host 1 is db1.abc.com
+       Host 2 is db2.abc.com
+       Host 3 is db3.abc.com
+    
+

Privilege Required +

None +

Related Information +

bos +

bos addhost +

bos removehost +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf107.htm b/doc/html/AdminReference/auarf107.htm new file mode 100644 index 0000000..29bd399 --- /dev/null +++ b/doc/html/AdminReference/auarf107.htm @@ -0,0 +1,136 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos listkeys

+ + + + + + + +

Purpose +

Displays the server encryption keys from the +/usr/afs/etc/KeyFile file +

Synopsis +

bos listkeys -server <machine name>  [-showkey]  [-cell <cell name>]  
+             [-noauth]  [-localauth]  [-help]
+   
+bos listk -se <machine name>  [-sh]  [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos listkeys command formats and displays the list of server +encryption keys from the /usr/afs/etc/KeyFile file on the server +machine named by the -server argument. +

To edit the list of keys, use the bos addkey and bos +removekey commands. +

Cautions +

Displaying actual keys on the standard output stream (by including the +-showkey flag) is a security exposure. Displaying a checksum +is sufficient for most purposes. +

Options +

-server +

Indicates the server machine from which to display the KeyFile +file. Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see the +introductory reference page for the bos command suite. +

For consistent performance in the cell, the output must be the same on +every server machine. The bos addkey reference page explains +how to keep the machines synchronized. +

-showkey +

Displays the octal digits that constitute each key. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The output includes one line for each server encryption key listed in the +KeyFile file, identified by its key version number. +

If the -showkey flag is included, the output displays the actual +string of eight octal numbers that constitute the key. Each octal +number is a backslash and three decimal digits. +

If the -showkey flag is not included, the output represents each +key as a checksum, which is a decimal number derived by encrypting a constant +with the key. +

Following the list of keys or checksums, the string Keys last +changed indicates when a key was last added to the KeyFile +file. The words All done indicate the end of the +output. +

For mutual authentication to work properly, the output from the command +kas examine afs must match the key or checksum with the same key +version number in the output from this command. +

Examples +

The following example shows the checksums for the keys stored in the +KeyFile file on the machine +fs3.abc.com. +

   % bos listkeys fs3.abc.com
+   key 1 has cksum 972037177
+   key 3 has cksum 2825175022
+   key 4 has cksum 260617746
+   key 6 has cksum 4178774593
+   Keys last changed on Mon Apr 12 11:24:46 1999.
+   All done.
+    
+

The following example shows the actual keys from the KeyFile +file on the machine fs6.abc.com. +

   % bos listkeys fs6.abc.com -showkey
+   key 0 is '\040\205\211\241\345\002\023\211'
+   key 1 is '\343\315\307\227\255\320\135\244'
+   key 2 is '\310\310\255\253\326\236\261\211'
+   Keys last changed on Wed Mar 31 11:24:46 1999.
+   All done.
+   
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf108.htm b/doc/html/AdminReference/auarf108.htm new file mode 100644 index 0000000..751b9ab --- /dev/null +++ b/doc/html/AdminReference/auarf108.htm @@ -0,0 +1,95 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos listusers

+ + + + + +

Purpose +

Lists the privileged users from the /usr/afs/etc/UserList file +

Synopsis +

bos listusers -server <machine name>  [-cell <cell name>]  
+              [-noauth]   [-localauth]   [-help]
+   
+bos listu -s <machine name>  [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos listusers command lists the user names from the +/usr/afs/etc/UserList file on the file server machine named by the +-server argument. The users are authorized to issue +privileged bos and vos commands. +

To edit the list of users, use the bos adduser and bos +removeuser commands. +

Options +

-server +

Indicates the server machine from which to display the UserList +file. Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see the +introductory reference page for the bos command suite. +

For consistent performance in the cell, the output must be the same on +every server machine. The bos adduser reference page +explains how to keep the machines synchronized. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The output lists the user name of each user entitled to issue privileged +bos and vos commands. +

Examples +

The following example lists the users from UserList file on the +machine fs4.abc.com. +

   % bos listusers fs4.abc.com
+   SUsers are: pat smith jones terry
+    
+

Privilege Required +

None +

Related Information +

bos +

bos adduser +

bos removeuser +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf109.htm b/doc/html/AdminReference/auarf109.htm new file mode 100644 index 0000000..9cc5cdc --- /dev/null +++ b/doc/html/AdminReference/auarf109.htm @@ -0,0 +1,139 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos prune

+ + + + + + + + + + + + + +

Purpose +

Removes obsolete versions of files from the /usr/afs/bin and +/usr/afs/logs directories +

Synopsis +

bos prune -server <machine name>  [-bak]  [-old]  [-core]  [-all]
+          [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+   
+bos p -s <machine name>  [-b]  [-o]  [-co]  [-a]  
+      [-ce <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos prune command removes files from the local disk of the +server machine named by the -server argument, as specified by one +or more of the following flags provided on the command line: +

The -bak flag removes all files from the +/usr/afs/bin directory that have a .BAK +extension. +
The -old flag removes all files from the +/usr/afs/bin directory that have a .OLD +extension. +
The -core flag removes all files from the +/usr/afs/logs directory that have a core. +prefix. +
The -all flag removes all three types of files at once. +

(If none of these flags are included, the command appears to succeed, but +removes no files at all.) +

To display the timestamp on the current, .BAK, and +.OLD versions of one or more files, use the bos +getdate command. +

Options +

-server +: Indicates the server machine from which to remove files. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +
-bak +: Removes all files from the /usr/afs/bin directory that have a +.BAK extension. Do not combine this flag and the +-all flag. +
-old +: Removes all files from the /usr/afs/bin directory that have a +.OLD extension. Do not combine this flag and the +-all flag. +
-core +: Removes all files from the /usr/afs/logs directory that have a +core. prefix. Do not combine this flag and the +-all flag. +
-all +: Combines the effect of the -bak, -old, and +-core flags. Do not combine this flag with any of those +three. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example removes all files from the /usr/afs/bin +directory on the machine fs3.abc.com that have a +.BAK or .OLD extension. +

   % bos prune -server fs3.abc.com -bak -old
+    
+

The following example removes all files from the /usr/afs/bin +directory on the machine db2.abc.com that have a +.BAK or .OLD extension, and all files from +the /usr/afs/logs directory that have a core. +prefix. +

   % bos prune -server db2.abc.com -all
+    
+

Privilege Required +

Related Information +

bos +

bos getdate +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf110.htm b/doc/html/AdminReference/auarf110.htm new file mode 100644 index 0000000..d0bc677 --- /dev/null +++ b/doc/html/AdminReference/auarf110.htm @@ -0,0 +1,112 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos removehost

+ + + + + +

Purpose +

Removes a database server machine from the +/usr/afs/etc/CellServDB file +

Synopsis +

bos removehost -server <machine name>  -host <host name>⁺ 
+               [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+  
+bos removeh -s <machine name>  -ho <host name>⁺  [-c <cell name>]  
+            [-n]  [-l]  [-he]
+

Description +

The bos removehost command removes the entry for each database +server machine specified with the -host argument from the +/usr/afs/etc/CellServDB file on the server machine named by the +-server argument. +

Cautions +

Options +

-server +

Indicates the server machine on which to change the +/usr/afs/etc/CellServDB file. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference page for +the bos command suite. +

-host +

Specifies the fully-qualified host name (such as +fs2.abc.com) of each database server machine to +remove from the CellServDB file. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command removes the former database server machine +db2.abc.com from the CellServDB file on +the system control machine fs1.abc.com. +

   % bos removehost -server fs1.abc.com -host db2.abc.com
+   
+

Privilege Required +

Related Information +

bos +

bos addhost +

bos listhosts +

IBM AFS Quick Beginnings +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf111.htm b/doc/html/AdminReference/auarf111.htm new file mode 100644 index 0000000..5f1322c --- /dev/null +++ b/doc/html/AdminReference/auarf111.htm @@ -0,0 +1,108 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos removekey

+ + + + + +

Purpose +

Removes a server encryption key from the /usr/afs/etc/KeyFile +file +

Synopsis +

bos removekey -server <machine name>  -kvno <key version number>⁺ 
+              [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+   
+bos removek -s <machine name>  -k <key version number>⁺  
+            [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos removekey command removes each specified encryption key +from the /usr/afs/etc/KeyFile file on the machine named by the +-server argument. Use the -kvno argument to +identify each key by its key version number; use the bos +listkeys command to display the key version numbers. +

Cautions +

Before removing a obsolete key, verify that the cell's maximum ticket +lifetime has passed since the current key was defined using the kas +setpassword and bos addkey commands. This ensures that +no clients still possess tickets encrypted with the obsolete key. +

Options +

-server +

-kvno +

Specifies the key version number of each key to remove. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command removes the keys with key version numbers 5 and 6 +from the KeyFile file on the system control machine +fs1.abc.com. +

   % bos removekey -server fs1.abc.com -kvno 5 6
+   
+

Privilege Required +

Related Information +

bos +

bos addkey +

bos listkeys +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf112.htm b/doc/html/AdminReference/auarf112.htm new file mode 100644 index 0000000..5fb99ce --- /dev/null +++ b/doc/html/AdminReference/auarf112.htm @@ -0,0 +1,100 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos removeuser

+ + + + + +

Purpose +

Removes a privileged user from the /usr/afs/etc/UserList file +

Synopsis +

bos removeuser -server <machine name>  -user <user names>⁺ 
+               [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+  
+bos removeu -s <machine name>  -u <user names>⁺  [-c <cell name>]  
+            [-n]  [-l]  [-h]
+

Description +

The bos removeuser command removes each user name specified with +the -user argument from the /usr/afs/etc/UserList file +on the machine named by the -server argument. +

Options +

-server +

-user +

Specifies each user name to remove. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example removes the users pat and jones +from the UserList file on the system control machine +fs1.abc.com. +

   % bos removeuser -server fs1.abc.com -user pat jones
+    
+

Privilege Required +

Related Information +

bos +

bos addkey +

bos listkeys +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf113.htm b/doc/html/AdminReference/auarf113.htm new file mode 100644 index 0000000..aa9ee58 --- /dev/null +++ b/doc/html/AdminReference/auarf113.htm @@ -0,0 +1,140 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos restart

+ + + + + + +

Purpose +

Restarts a server process +

Synopsis +

bos restart -server <machine name>  [-instance <instances>⁺]  [-bosserver]  
+            [-all]  [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+   
+bos res -s <machine name>  [-i <instances>⁺]  [-b]  [-a]  
+        [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos restart command stops and immediately restarts server +processes on the server machine named by the -server +argument. Indicate which process or processes to restart by providing +one of the following arguments: +

The -instance argument names each AFS server process to stop +and restart immediately, regardless of its status flag in the +/usr/afs/local/BosConfig file. Do not include +bosserver in the list of processes; use the +-bosserver flag instead. +
The -bosserver flag stops all AFS server processes running on +the machine, including the BOS Server. A new BOS Server starts +immediately, and it starts a new instance of each process that is marked with +the Run status flag in the BosConfig file. +
The -all flag stops all AFS server processes running on the +machine, except the BOS Server, and immediately restarts the processes that +are marked with the Run status flag in the BosConfig +file. +

This command does not change a process's status flag in the +BosConfig file. +

Options +

-server +: Indicates the server machine on which to restart each process. +Identify the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +
-instance +: Names each process to stop and then restart immediately regardless of its +status flag setting. Use the process name assigned with the +-instance argument to the bos create command. The +output from the bos status command lists the names. Provide +this flag or one of the -bosserver or -all options, but +do not combine them. +
-bosserver +: Stops all AFS server processes running on the machine, including the BOS +Server. A new BOS Server instance immediately starts, and starts all +processes marked with the Run status flag in the +BosConfig file. Provide this flag or one of the +-instance or -all options, but do not combine +them. +
-all +: Stops all AFS server processes running on the machine other than the BOS +Server, and immediately restarts the processes marked with the Run +status flag in the BosConfig file. Provide this flag or one +of the -instance or -bosserver options, but do not +combine them. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command stops and restarts all processes running on the +machine fs3.abc.com, including the BOS Server. +

   % bos restart -server fs3.abc.com -bosserver
+    
+

The following command stops and restarts all processes running on the +machine fs5.abc.com, excluding the BOS Server. +

   % bos restart -server fs5.abc.com -all
+    
+

The following command stops and restarts the Protection Server and Volume +Location (VL) Server processes on the machine +db3.abc.com: +

   % bos restart -server db3.abc.com -instance ptserver vlserver
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf114.htm b/doc/html/AdminReference/auarf114.htm new file mode 100644 index 0000000..05d25e9 --- /dev/null +++ b/doc/html/AdminReference/auarf114.htm @@ -0,0 +1,298 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos salvage

+ + + + + + + + +

Purpose +

Restores internal consistency to a file system or volume +

Synopsis +

bos salvage -server <machine name>  [-partition <salvage partition>]
+            [-volume <salvage volume number or volume name>]
+            [-file <salvage log output file>]  [-all]  [-showlog] 
+            [-parallel <# of max parallel partition salvaging>]  
+            [-tmpdir <directory to place tmp files>] 
+            [-orphans <ignore | remove | attach>] 
+            [-cell <cell name>]
+            [-noauth]  [-localauth]  [-help]
+   
+bos sa -se <machine name>  [-part <salvage partition>]
+       [-v <salvage volume number or volume name>]  
+       [-f <salvage log output file>]  [-a]  [-sh] 
+       [-para <# of max parallel partition salvaging>]  
+       [-t <directory to place tmp files>]   
+       [-o <ignore | remove | attach>] 
+       [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos salvage command salvages (restores internal consistency +to) one or more volumes on the file server machine named by the +-server argument. When processing one or more partitions, +the command restores consistency to corrupted read/write volumes where +possible. For read-only or backup volumes, it inspects only the volume +header: +

If the volume header is corrupted, the Salvager removes the volume +completely and records the removal in its log file, +/usr/afs/logs/SalvageLog. Issue the vos release +or vos backup command to create the read-only or backup volume +again. +
If the volume header is intact, the Salvager skips the volume (does not +check for corruption in the contents). However, if the File Server +notices corruption as it initializes, it sometimes refuses to attach the +volume or bring it online. In this case, it is simplest to remove the +volume by issuing the vos remove or vos zap +command. Then issue the vos release or vos backup +command to create it again. +

Use the indicated arguments to salvage a specific number of volumes: +

To process all volumes on a file server machine, provide the +-server argument and the -all flag. No volumes on +the machine are accessible to Cache Managers during the salvage operation, +because the BOS Server stops the File Server and Volume Server processes while +the Salvager runs. The BOS Server automatically restarts them when the +operation completes. +
To process all volumes on one partition, provide the -server +and -partition arguments. As for a salvage of the entire +machine, no volumes on the machine are accessible to Cache Managers during the +salvage operation. The BOS Server automatically restarts the File +Server and Volume Server when the operation completes. +
To salvage only one read/write volume, combine the -server, +-partition, and -volume arguments. Only that +volume is inaccessible to Cache Managers, because the BOS Server does not +shutdown the File Server and Volume Server processes during the salvage of a +single volume. Do not name a read-only or backup volume with the +-volume argument. Instead, remove the volume, using the +vos remove or vos zap command. Then create a new +copy of the volume with the vos release or vos backup +command. +

During the salvage of an entire machine or partition, the bos +status command reports the fs process's auxiliary status +as Salvaging file system. +

The Salvager always writes a trace to the +/usr/afs/logs/SalvageLog file on the file server machine where it +runs. To record the trace in another file as well (either in AFS or on +the local disk of the machine where the bos salvage command is +issued), name the file with the -file argument. To display +the trace on the standard output stream as it is written to the +/usr/afs/logs/SalvageLog file, include the -showlog +flag. +

Cautions +

Running this command can result in data loss if the Salvager process can +repair corruption only by removing the offending data. Consult the +IBM AFS Administration Guide for more information. +

Options +

-server +

Indicates the file server machine on which to salvage volumes. +Identify the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +

-partition +

Specifies a single partition on which to salvage all volumes. +Provide the complete partition name (for example /vicepa) or one of +the following abbreviated 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
+    
+

-volume +

Specifies the name or volume ID number of a read/write volume to +salvage. The -partition argument must be provided along with +this one. +

-file +

Specifies the complete pathname of a file into which to write a trace of +the salvage operation, in addition to the /usr/afs/logs/SalvageLog +file on the server machine. If the file pathname is local, the trace is +written to the specified file on the local disk of the machine where the +bos salvage command is issued. If the -volume +argument is included, the file can be in AFS, though not in the volume being +salvaged. Do not combine this argument with the -showlog +flag. +

-all +

Salvages all volumes on all of the partitions on the machine named by the +-server argument. +

-showlog +

Displays the trace of the salvage operation on the standard output stream, +as well as writing it to the /usr/afs/logs/SalvageLog file. +Do not combine this flag with the -file argument. +

-parallel +

Specifies the maximum number of Salvager subprocesses to run in +parallel. Provide one of three values: +

An integer from the range 1 to 32. A value of +1 means that a single Salvager process salvages the partitions +sequentially. +
The string all to run up to four Salvager subprocesses in +parallel on partitions formatted as logical volumes that span multiple +physical disks. Use this value only with such logical volumes. +
The string all followed immediately (with no intervening space) +by an integer from the range 1 to 32, to run the +specified number of Salvager subprocesses in parallel on partitions formatted +as logical volumes. Use this value only with such logical +volumes. +

The BOS Server never starts more Salvager subprocesses than there are +partitions, and always starts only one process to salvage a single +volume. If this argument is omitted, up to four Salvager subprocesses +run in parallel. +

-tmpdir +

Specifies the full pathname of a local disk directory to which the +Salvager process writes temporary files as it runs. If this argument is +omitted, or specifies an ineligible or nonexistent directory, the Salvager +process writes the files to the partition it is currently salvaging. +

-orphans +

Controls how the Salvager handles orphaned files and directories. +Choose one of the following three values: +

ignore +

Leaves the orphaned objects on the disk, but prints a message to the +/usr/afs/logs/SalvageLog file reporting how many orphans were found +and the approximate number of kilobytes they are consuming. This is the +default if the -orphans argument is omitted. +

remove +

Removes the orphaned objects, and prints a message to the +/usr/afs/logs/SalvageLog file reporting how many orphans were +removed and the approximate number of kilobytes they were consuming. +

attach +

Attaches the orphaned objects by creating a reference to them in the vnode +of the volume's root directory. Since each object's actual +name is now lost, the Salvager assigns each one a name of the following +form: +

_ _ORPHANFILE_ _.index for files +

_ _ORPHANDIR_ _.index for directories +

where index is a two-digit number that uniquely identifies each +object. The orphans are charged against the volume's quota and +appear in the output of the ls command issued against the +volume's root directory. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command salvages all volumes on the /vicepd +partition of the machine db3.abc.com: +

   % bos salvage -server db3.abc.com -partition /vicepd
+   
+

The following command salvages the volume with volume ID number 536870988 +on partition /vicepb of the machine +fs2.abc.com: +

   % bos salvage -server fs2.abc.com -partition /vicepb -volume 536870988
+   
+

The following command salvages all volumes on the machine +fs4.abc.com. Six Salvager processes run in +parallel rather than the default four. +

   % bos salvage -server fs4.abc.com -all -parallel 6
+    
+

Privilege Required +

Related Information +

bos +

IBM AFS Administration Guide +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf115.htm b/doc/html/AdminReference/auarf115.htm new file mode 100644 index 0000000..c53af23 --- /dev/null +++ b/doc/html/AdminReference/auarf115.htm @@ -0,0 +1,112 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos setauth

+ + + + + +

Purpose +

Sets authorization checking requirements for all server processes +

Synopsis +

bos setauth -server <machine name>  
+     -authrequired <on or off: authentication required for admin requests>
+     [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+   
+bos seta -s <machine name>
+         -a <on or off: authentication required for admin requests>  
+         [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos setauth command enables or disables authorization +checking on the server machine named by the -server +argument. When authorization checking is enabled (the normal case), the +AFS server processes running on the machine verify that the issuer of a +command meets its privilege requirements. When authorization checking +is disabled, server processes perform any action for anyone, including the +unprivileged user anonymous; this security exposure precludes +disabling of authorization checking except during installation or +emergencies. +

To indicate to the server processes that authorization checking is +disabled, the BOS Server creates the zero-length file +/usr/afs/local/NoAuth on its local disk. All AFS server +processes constantly monitor for the NoAuth file's presence +and do not check for authorization when it is present. The BOS Server +removes the file when this command is used to reenable authorization +checking. +

Cautions +

Do not create the NoAuth file directly, except when directed by +instructions for dealing with emergencies (doing so requires being logged in +as the local superuser root). Use this command +instead. +

Options +

-server +: Indicates the server machine on which to enable or disable authorization +checking. Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see the +introductory reference page for the bos command suite. +
-authrequired +: Enables authorization checking if the value is on, or disables +it if the value is off. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example disables authorization checking on the machine +fs7.abc.com: +

   % bos setauth -server fs7.abc.com -authrequired off
+    
+

Privilege Required +

Related Information +

NoAuth +

bos +

bos restart +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf116.htm b/doc/html/AdminReference/auarf116.htm new file mode 100644 index 0000000..e2ef79f --- /dev/null +++ b/doc/html/AdminReference/auarf116.htm @@ -0,0 +1,128 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos setcellname

+ + + + + + + + +

Purpose +

Sets the cell's name in the /usr/afs/etc/ThisCell and +/usr/afs/etc/CellServDB files +

Synopsis +

bos setcellname -server <machine name>  -name <cell name> 
+                [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+   
+bos setc -s <machine name>  -n <cell name>  [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos setcellname command establishes the cell's name and +makes the server machine named by the -server argument a member of +it, by recording the value of the -name argument in two files which +it creates on the local disk: +

/usr/afs/etc/ThisCell +
/usr/afs/etc/CellServDB. The cell name appears on the +first line in the file, preceded by the required > symbol. +The machine name specified with the -server argument appears on the +second line along with its IP address as obtained from the cell's naming +service. The machine is thus designated as the cell's first +database server machine. +

Cautions +

Issue this command only when the installing the cell's first AFS +server machine. The IBM AFS Quick Beginnings explains how to +copy over the ThisCell and CellServDB files from this or +another appropriate machine during installation of additional server +machines. +

Be sure to choose a satisfactory cell name when issuing this command, +because changing a cell's name is very complicated; for one thing, +it requires changing every password in the Authentication Database. +Consult the IBM AFS Administration Guide for advice on choosing a +cell name. If changing the cell's name is absolutely necessary, +contact AFS Product Support for complete instructions. +

Options +

-server +: Indicates the server machine on which to set the cell name in the +ThisCell and CellServDB file. It is always the +first machine installed in a cell. Identify the machine by IP address +or its host name (either fully-qualified or abbreviated unambiguously). +For details, see the introductory reference page for the bos +command suite. +
-name +: Defines the cell name, using standard Internet domain name format (the +actual domain name is usually appropriate). Examples are +abc.com for the ABC Corporation and +stateu.edu for the State University. It must match +the value of the -cell argument, if that is provided. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command defines the cell name abc.com in +the ThisCell and CellServDB files on the machine +fs1.abc.com as it is installed as the cell's +first server machine. +

   % bos setcellname -server fs1.abc.com -name abc.com
+   
+

Privilege Required +

Authorization checking is normally turned off during installation, which is +the only recommended time to use this command; in this case no privilege +is required. If authorization checking is turned on, the issuer must be +listed in the /usr/afs/etc/UserList file on the machine named by +the -server argument, or must be logged in as the local superuser +root if the -localauth flag is included. +

Related Information +

bos +

IBM AFS Quick Beginnings +

IBM AFS Administration Guide +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf117.htm b/doc/html/AdminReference/auarf117.htm new file mode 100644 index 0000000..deafd52 --- /dev/null +++ b/doc/html/AdminReference/auarf117.htm @@ -0,0 +1,158 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos setrestart

+ + + + + + +

Purpose +

Sets the date and time at which the BOS Server restarts processes +

Synopsis +

bos setrestart -server <machine name>  -time <time to restart server>  
+               [-general]   [-newbinary]  [-cell <cell name>]  
+               [-noauth]  [-localauth]  [-help]  
+    
+bos setr -s <machine name>  -t <time to restart server>  [-g]  [-ne] 
+         [-c <cell name>]  [-no]  [-l]  [-h]
+

Description +

The bos setrestart command records in the +/usr/afs/local/BosConfig file the times at which the BOS Server +running on the server machine named by the -server argument +performs two types of restarts: +

A general restart. By default, once per week the BOS +Server restarts itself and then any AFS process marked with the Run +status flag in the BosConfig file (equivalent in effect to issuing +the bos restart command with the -bosserver +flag). The default setting is 4:00 a.m. each Sunday +morning. +
A binary restart. By default, once per day the BOS +Server restarts any currently running process for which the timestamp on the +binary file in the /usr/afs/bin directory is later than the time +the process last started or restarted. The default is 5:00 +a.m. each day. +

Cautions +

Restarting a process makes it unavailable for a period of time. The +fs process has potentially the longest outage, depending on how +many volumes the file server machine houses (the File Server and Volume Server +reattach each volume when they restart). The default settings are +designed to coincide with periods of low usage, so that the restarts disturb +the smallest possible number of users. +

If the setting specified with the -time argument is within one +hour of the current time, the BOS Server does not restart any processes until +the next applicable opportunity (the next day for binary restarts, or the next +week for general restarts). +

The command changes only one type of restart setting at a time; issue +the command twice to change both settings. +

Options +

-server +

Indicates the server machine on which to set a new restart time. +Identify the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +

-time +

Specifies the restart time. By convention the general restart is +defined as weekly (specifies both a day and a time), and the binary restart is +defined as daily (specifies only a time). However, it is acceptable to +define a daily general restart or weekly binary restart. +

There are four acceptable values for either type of restart setting: +

The string never, which directs the BOS Server never to perform +the indicated type of restart. +
The string now, which directs the BOS Server to perform the +restart immediately and never again. +
A time of day (the conventional type of value for the binary restart +time). Separate the hours and minutes with a colon +(hh:MM), and use either 24-hour format, or a value +in the range from 1:00 through 12:59 with +the addition of am or pm. For example, both +14:30 and "2:30 pm" indicate 2:30 in +the afternoon. Surround this parameter with double quotes (" +") if it contains a space. +
A day of the week and time of day, separated by a space and surrounded +with double quotes (" "). This is the conventional type of +value for the general restart. For the day, provide either the whole +name or the first three letters, all in lowercase letters (sunday +or sun, thursday or thu, and so on). +For the time, use the same format as when specifying the time alone. +

-general +

Sets the general restart time. +

-newbinary +

Sets the binary restart time. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command sets the general restart time on the machine +fs4.abc.com to Saturday at 3:30 am. +

   % bos setrestart -server fs4.abc.com -time "sat 3:30" -general
+   
+

The following command sets the binary restart time on the machine +fs6.abc.com to 11:45 pm. +

   % bos setrestart -server fs6.abc.com -time 23:45 -newbinary
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf118.htm b/doc/html/AdminReference/auarf118.htm new file mode 100644 index 0000000..6dac75a --- /dev/null +++ b/doc/html/AdminReference/auarf118.htm @@ -0,0 +1,122 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos shutdown

+ + + + + + +

Purpose +

Stops a process without changing its status flag in the +/usr/afs/local/BosConfig file +

Synopsis +

bos shutdown -server <machine name>  [-instance <instances>⁺]  [-wait]  
+             [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+    
+bos sh -s <machine name>  [-i <instances>⁺]  [-w]  
+       [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos shutdown command stops, on the server machine named by +the -server argument, either +

All of the currently running AFS server processes, except the BOS Server +
Only the processes specified by the -instance argument +

This command does not change a process's status flag in the +/usr/afs/local/BosConfig file, but only in the BOS Server's +memory. To stop a process and change its BosConfig status +flag, use the bos stop command instead. +

Once stopped with this command, a process does not run again until an +administrator starts it by using the bos start, bos +startup, or bos restart command, or until the BOS Server +restarts (assuming that the process's BosConfig status flag is +Run). +

Options +

-server +: Indicates the server machine on which to stop processes. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +
-instance +: Names each process to stop. Use the process name assigned with the +-instance argument to the bos create command. The +output from the bos status command lists the names. Omit +this argument to stop all processes other than the BOS Server. +
-wait +: Delays the return of the command shell prompt until all processes actually +stop. If this argument is omitted, the prompt returns almost +immediately even if all processes are not stopped. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command stops all processes other than the BOS Server on the +machine fs3.abc.com. +

   % bos shutdown fs3.abc.com
+   
+

The following command stops the upserver process (server portion +of the Update Server) on the machine +fs5.abc.com. +

   % bos shutdown -server fs5.abc.com -instance upserver
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf119.htm b/doc/html/AdminReference/auarf119.htm new file mode 100644 index 0000000..48a3447 --- /dev/null +++ b/doc/html/AdminReference/auarf119.htm @@ -0,0 +1,108 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos start

+ + + + + + + + +

Purpose +

Starts a process after setting its status flag in the +/usr/afs/local/BosConfig file +

Synopsis +

bos start -server <machine name>  -instance <server process name>⁺ 
+          [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+    
+bos start -s <machine name>  -i <server process name>⁺  
+          [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos start command sets the status flag for each process +specified by the -instance argument to Run in the +/usr/afs/local/BosConfig file and in the BOS Server's memory +on the server machine named by the -server argument, then starts +it. If the process is already running, the command's only effect +is to guarantee that the status flag is Run; it does not +restart the process. +

To start a process without changing its status flag in the +BosConfig file, use the bos startup command +instead. +

Options +

-server +: Indicates the server machine on which to start processes. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +
-instance +: Names each process to start. Use the process name assigned with the +-instance argument to the bos create command. The +output from the bos status command lists the names. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command changes the status flag for the +upclientbin and upclientetc processes to Run +in the BosConfig file on the machine +fs6.abc.com and starts them running. +

   % bos start -server fs6.abc.com -instance upclientbin upclientetc
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf120.htm b/doc/html/AdminReference/auarf120.htm new file mode 100644 index 0000000..9a6aa54 --- /dev/null +++ b/doc/html/AdminReference/auarf120.htm @@ -0,0 +1,112 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos startup

+ + + + + + +

Purpose +

Starts a process without changing its status flag in the +/usr/afs/local/BosConfig file +

Synopsis +

bos startup -server <machine name>  [-instance <instances>⁺] 
+            [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+    
+bos startu -s <machine name>  [-i <instances>⁺]  
+           [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos startup command starts, on the server machine named by +the -server argument, either +

All AFS server processes not currently running but marked with the +Run status flag in the /usr/afs/local/BosConfig file +
Each process specified by -instance argument, even if its +status flag in the BosConfig file is NotRun. +

To start a process and set its BosConfig status flag to +Run, use the bos start command instead. +

Options +

-server +: Indicates the server machine on which to start processes. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +
-instance +: Names each process to start. Use the process name assigned with the +-instance argument to the bos create command. The +output from the bos status command lists the names. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command starts all processes marked with status flag +Run in the BosConfig file on the machine +fs3.abc.com that are not currently running. +

   % bos startup fs3.abc.com
+   
+

The following command starts the buserver, kaserver, +ptserver, and vlserver processes running on the machine +db2.abc.com, even if their status flags in the +BosConfig file are NotRun. +

   % bos startup -server db2.abc.com -instance buserver kaserver ptserver vlserver
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf121.htm b/doc/html/AdminReference/auarf121.htm new file mode 100644 index 0000000..fc10548 --- /dev/null +++ b/doc/html/AdminReference/auarf121.htm @@ -0,0 +1,235 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos status

+ + + + + + + +

Purpose +

Displays the status of server processes +

Synopsis +

bos status -server <machine name>  [-instance <server process name>⁺]  
+           [-long]  [-cell <cell name>]  [-noauth]  [-localauth]  [-help] 
+    
+bos stat -s <machine name>  [-i <server process name>⁺] 
+         [-lon]  [-c <cell name>]  [-n]  [-loc]  [-h] 
+

Description +

The bos status command reports the status of processes on the +server machine named by the -server argument, either +

All of the AFS server processes listed in the +/usr/afs/local/BosConfig file +
Only these processes named by the -instance argument +

Options +

-server +: Indicates the server machine for which to report server process +status. Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see the +introductory reference page for the bos command suite. +
-instance +: Names each process for which to report status. Use the process name +assigned with the -instance argument to the bos +command. The output from the bos status command lists the +names. +
-long +: Produces more detailed status information. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output for a process includes at least one line, which reports one of +the following as the process's current status: +

currently running normally. The process's status +flag in the BosConfig file is Run. For +cron entries, this message indicates only that the command is +scheduled to run, not necessarily that it was executing when the bos +status command was issued. +
disabled. The process is not running, and its +BosConfig status flag is NotRun. +
temporarily disabled. The process is not running +although its status flag in the BosConfig file is +Run. Either an administrator used the bos +shutdown command to stop it, or the +
BOS Server stopped trying to restart it after numerous failed +attempts. In the second case, the auxiliary message is stopped for + too many errors. +
temporarily enabled. The process is running although its +status flag in the BosConfig file is NotRun. An +administrator has used the bos startup command to start it. +

If one of the following special circumstances applies to the process, the +indicated message appears in its entry: +

has core file. The process failed and created a core +file in the /usr/afs/logs directory. If the BOS Server was +able to restart the process after the failure, the primary status is +currently running normally. +
stopped for too many errors. The reason for the primary +status temporarily disabled is that the BOS Server's attempts +to restart the process all failed. +

The entry for the fs process always includes a second line to +report the process's Auxiliary status, which is one of the +following: +

file server running. The File Server and Volume Server +components of the File Server process are running normally. +
salvaging file system. The Salvager is running, so the +File Server and Volume Server are temporarily disabled. The BOS Server +restarts them as soon as the Salvager is finished. +

The entry for a cron process includes an Auxiliary +status that reports when the command will next execute. +

If the -long flag is used, each entry includes the following +additional information: +

The process's type (simple, fs, or +cron). +
The day and time the process last started or restarted. +
The number of proc starts, which is how many times the BOS +Server has started or restarted the process since it started itself. +
The Last exit time when the process (or one of the component +processes in the fs process) last terminated. This line does +not appear if the process has not terminated since the BOS Server +started. +
The Last error exit time when the process (or one of the +component processes in the fs process) last failed due to an +error. A further explanation such as due to shutdown request +sometimes appears. This line does not appear if the process has not +failed since the BOS Server started. +
Each command that the BOS Server invokes to start the process, as +specified by the -cmd argument to the bos create +command. +
The pathname of the notifier program that the BOS Server invokes when the +process terminates (if any), as specified by the -notifier argument +to the bos create command. +

If the -long flag is provided and the BOS Server discovers that +the mode bits on files and subdirectories in the local /usr/afs +directory differ from the expected values, it prints the following warning +message: +

   Bosserver reports inappropriate access on server directories
+   
+

The following chart summarizes the expected mode bit settings. A +question mark indicates that the BOS Server does not check that bit. +
+ + + + + + + + + + +
/usr/afs + drwxr?xr-x +
/usr/afs/backup + drwx???--- +
/usr/afs/bin + drwxr?xr-x +
/usr/afs/db + drwx???--- +
/usr/afs/etc + drwxr?xr-x +
/usr/afs/etc/KeyFile + -rw????--- +
/usr/afs/etc/UserList + -rw?????-- +
/usr/afs/local + drwx???--- +
/usr/afs/logs + drwxr?xr-x +
+

Examples +

The following example command displays the status of processes on the +machine fs3.abc.com: +

   % bos status fs3.abc.com
+   Instance buserver, currently running normally.
+   Instance kaserver, currently running normally.
+   Instance ptserver, currently running normally.
+   Instance vlserver, currently running normally.
+   Instance fs, has core file, currently running normally.
+       Auxiliary status is: file server running.
+   Instance upserver, currently running normally.
+   Instance runntp, currently running normally.
+   
+

The following example command displays a detailed status report for the +fs and ptserver processes on the machine +fs1.abc.com. +

   % bos status -server fs1.abc.com -instance fs ptserver -long
+   Instance fs, (type is fs), currently running normally.
+      Auxiliary status is: file server running.
+      Process last started at Wed Jan 7 5:34:49 1998 (3 proc starts)
+      Last exit at Wed Jan 7 5:34:49 1998 
+      Last error exit at Wed Jan 7 5:34:49 1998, due to shutdown 
+          request
+      Command 1 is '/usr/afs/bin/fileserver'
+      Command 2 is '/usr/afs/bin/volserver'
+      Command 3 is '/usr/afs/bin/salvager'
+   Instance ptserver, (type is simple) currently running normally.
+      Process last started at Tue Jan 6 8:29:19 1998 (1 proc starts)
+      Command 1 is '/usr/afs/bin/ptserver'
+   
+

Privilege Required +

None +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf122.htm b/doc/html/AdminReference/auarf122.htm new file mode 100644 index 0000000..af761e3 --- /dev/null +++ b/doc/html/AdminReference/auarf122.htm @@ -0,0 +1,106 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos stop

+ + + + + + + + +

Purpose +

Stops a process after changing its status flag in the +/usr/afs/local/BosConfig file +

Synopsis +

bos stop -server <machine name>  -instance <server process name>⁺ 
+         [-wait]  [-cell <cell name>]  [-noauth]  [-localauth]  [-help]
+     
+bos sto -s <machine name>  -i <server process name>⁺
+        [-w]  [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos stop command sets the status flag for each process +specified with the -instance argument to NotRun in the +/usr/afs/local/BosConfig file on the server machine named by the +-server argument, then stops it. +

To stop a process without changing its BosConfig status flag, +use the bos shutdown command instead. +

Options +

-server +: Indicates the server machine on which to stop processes. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see the introductory reference +page for the bos command suite. +
-instance +: Names each process to stop. Use the process name assigned with the +-instance argument to the bos create command. The +output from the bos status command lists the names. +
-wait +: Delays the return of the command shell prompt until all processes actually +stop. If this argument is omitted, the prompt returns almost +immediately even if all processes are not stopped. +
-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 bos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The bos command +interpreter presents the ticket to the BOS Server during mutual +authentication. Do not combine this flag with the -cell or +-noauth options. For more details, see the introductory +bos reference page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example command stops the upserver and +runntp on the machine fs7.abc.com. +

   % bos stop -server fs7.abc.com -instance upserver runntp
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf123.htm b/doc/html/AdminReference/auarf123.htm new file mode 100644 index 0000000..d2c463f --- /dev/null +++ b/doc/html/AdminReference/auarf123.htm @@ -0,0 +1,122 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bos uninstall

+ + + + + + + + + +

Purpose +

Reverts to the former version of a process's binary file +

Synopsis +

bos uninstall -server <machine name>  -file <files to uninstall>⁺ 
+              [-dir <destination dir>]  [-cell <cell name>]  
+              [-noauth]  [-localauth]  [-help]
+   
+bos u -s <machine name>  -f <files to uninstall>⁺  [-d <destination dir>] 
+      [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The bos uninstall command replaces each binary file specified by +the -file argument with its .BAKversion on the +server machine named by the -server argument, which is normally the +binary distribution machine for its CPU/operating system type. It also +changes the extension on the current .OLD version (if any) +to .BAK. Each binary file must reside in the local +/usr/afs/bin directory unless the -dir argument names an +alternate directory. +

To start using the reverted binary immediately, issue the bos +restart command. Otherwise, the BOS Server automatically restarts +the process at the time defined in the /usr/afs/local/BosConfig +file; use the bos getrestart command to display the time and +the bos setrestart time to set it. +

Options +

-server +

Indicates the binary distribution machine on which to revert to the +.BAK version of binaries. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference page for +the bos command suite. +

-file +

Names each binary file to replace with its .BAK +version. +

-dir +

Provides the complete pathname of the local disk directory containing each +file named by the -file argument. It is necessary only if +the binaries are not in the /usr/afs/bin directory. +

-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 bos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory bos reference +page. +

-localauth +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example command overwrites the +/usr/afs/bin/kaserver file on the machine +fs4.abc.com with its .BAKversion, +and the current .BAK version by the +.OLDversion. +

   % bos uninstall -server fs4.abc.com -file kaserver
+   
+

Privilege Required +

Related Information +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf124.htm b/doc/html/AdminReference/auarf124.htm new file mode 100644 index 0000000..75b0158 --- /dev/null +++ b/doc/html/AdminReference/auarf124.htm @@ -0,0 +1,164 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

bosserver

+ + + +

Purpose +

Initializes the BOS Server +

Synopsis +

bosserver [-noauth]  [-log]  [-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 bosserver command initializes the Basic OverSeer (BOS) +Server (bosserver process). In the conventional +configuration, the binary file is located in the /usr/afs/bin +directory on a file server machine. +

The BOS Server must run on every file server machine and helps to automate +file server administration by performing the following tasks: +

Monitors the other AFS server processes on the local machine, to make sure +they are running correctly. +
Automatically restarts failed processes, without contacting a human +operator. When restarting multiple server processes simultaneously, the +BOS Server takes interdependencies into account and initiates restarts in the +correct order. + + +
Processes commands from the bos suite that administrators issue +to verify the status of server processes, install and start new processes, +stop processes either temporarily or permanently, and restart halted +processes. +
Manages system configuration information: the files that list the +cell's server encryption keys, database server machines, and users +privileged to issue commands from the bos and vos +suites. +

The BOS Server logs a default set of important events in the file +/usr/afs/logs/BosLog. To record the name of any user who +performs a privileged bos command (one that requires being listed +in the /usr/afs/etc/UserList file), add the -log +flag. To display the contents of the BosLog file, use the +bos getlog command. +

The first time that the BOS Server initializes on a server machine, it +creates several files and subdirectories in the local /usr/afs +directory, and sets their mode bits to protect them from unauthorized +access. Each time it restarts, it checks that the mode bits still +comply with the settings listed in the following chart. A question mark +indicates that the BOS Server initially turns off the bit (sets it to the +hyphen), but does not check it at restart. +
+ + + + + + + + + + +
/usr/afs + drwxr?xr-x +
/usr/afs/backup + drwx???--- +
/usr/afs/bin + drwxr?xr-x +
/usr/afs/db + drwx???--- +
/usr/afs/etc + drwxr?xr-x +
/usr/afs/etc/KeyFile + -rw????--- +
/usr/afs/etc/UserList + -rw?????-- +
/usr/afs/local + drwx???--- +
/usr/afs/logs + drwxr?xr-x +
+

If the mode bits do not comply, the BOS Server writes the following warning +to the BosLog file: +

   Bosserver reports inappropriate access on server directories
+   
+

However, the BOS Server does not reset the mode bits, so the administrator +can set them to alternate values if desired (with the understanding that the +warning message then appears at startup). +

Options +

-noauth +: Assigns the unprivileged identity anonymous to the issuer, +which is useful only when authorization checking is disabled on the server +machine (for instance, during the installation of a file server +machine.) +
-log +: Records in the /usr/afs/logs/BosLog file the names of all users +who successfully issue a privileged bos command (one that requires +being listed in the /usr/afs/etc/UserList file). +
-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 following command initializes the BOS Server and logs the names of +users who issue privileged bos commands. +

   % bosserver -log &
+   
+

Privilege Required +

The issuer most be logged onto a file server machine as the local superuser +root. +

Related Information +

BosLog +

bos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf125.htm b/doc/html/AdminReference/auarf125.htm new file mode 100644 index 0000000..3fce266 --- /dev/null +++ b/doc/html/AdminReference/auarf125.htm @@ -0,0 +1,147 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

buserver

+ + + + + + +

Purpose +

Initializes the Backup Server +

Synopsis +

buserver [-database <database directory>] 
+         [-cellservdb <cell configuration directory>]
+         [-resetdb]  [-noauth]  [-smallht] 
+         [-servers <list of ubik database servers>⁺]  
+         [-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 buserver command initializes the Backup Server, which runs +on database server machines and maintains the Backup Database. In the +conventional configuration, the binary file is located in the +/usr/afs/bin directory on a file server machine. +

The buserver command is not normally issued at the command shell +prompt, but rather placed into a database server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a file server machine as the local superuser +root. +

As it initializes, the Backup Server process creates the two files that +constitute the Backup Database, bdb.DB0 and +bdb.DBSYS1, in the /usr/afs/db directory if they +do not already exist. The Backup Database houses information about +volume sets and entries, the dump hierarchy, Tape Coordinators, and previously +performed dump sets. Use the commands in the backup suite to +administer the database. +

The Backup Server records a trace of its activity in the +/usr/afs/logs/BackupLog file. Use the bos getlog +command to display the contents of the file. +

Cautions +

The buserver process reserves port 7021 for its +use. Unexpected behavior can occur if another process tries to reserve +this port while the buserver process is running. +

Options +

-database +: Specifies the pathname of an alternate directory for the Backup Database +files, ending in a final slash (/). If this argument is not +provided, the default is the /usr/afs/db directory. +
-cellservdb +: Specifies the pathname of the directory from which the Backup Server reads +in an alternate version of the CellServDB file. This +argument is mandatory for correct functioning when the Backup Server is +running on a subset of the cell's database server machines that is not a +majority of the machines listed in the standard +/usr/afs/etc/CellServDB file (which the Backup Server consults if +this argument is not provided). It is not appropriate in any other +circumstances. +
-resetdb +: Removes all of the information in the Backup Database files in the +/usr/afs/db directory, leaving zero-length versions of them. +The backup operator must recreate the configuration entries in the database +(for volume sets, the dump hierarchy and so on) before performing backup +operations. +
-noauth +: Establishes an unauthenticated connection between the issuer and the +Backup Server, in which the Backup Server treats the issuer as the +unprivileged user anonymous. It is useful only when +authorization checking is disabled on the database server machine. In +normal circumstances, the Backup Server allows only authorized (privileged) +users to issue commands that affect or contact the Backup Database, and +refuses to perform such an action even if the -noauth flag is +used. +
-smallht +: Directs the Backup Server to use smaller internal hash tables for the +Backup Database, which reduces memory requirements but can make data access +take longer. +
-servers +: Specifies the database server machines on which to start the Backup +Server. Use this argument if running the Backup Server on a subset of +the database server machines that is not a majority of the machines listed in +the /usr/afs/etc/CellServDB file. +
-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 following example bos create command creates a +buserver process on the file server machine +fs3.abc.com. It appears here on two lines only +for legibility. +

   % bos create -server fs3.abc.com -instance buserver  \
+                -type simple -cmd /usr/afs/bin/buserver
+   
+

Privilege Required +

The issuer must be logged in as the superuser root on a file +server machine to issue the command at a command shell prompt. It is +conventional instead to create and start the process by issuing the bos +create command. +

Related Information +

BackupLog +

bdb.DB0 and bdb.DBSYS1 +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf126.htm b/doc/html/AdminReference/auarf126.htm new file mode 100644 index 0000000..d114049 --- /dev/null +++ b/doc/html/AdminReference/auarf126.htm @@ -0,0 +1,194 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

butc

+ + + + + + +

Purpose +

Initializes the Tape Coordinator process +

Synopsis +

butc [-port <port offset>]  [-debuglevel < 0 | 1 | 2 >]  
+     [-cell <cell name>]  [-noautoquery]  
+     [-localauth]  [-help]
+        
+butc [-p <port offset>]  [-d < 0 | 1 | 2 >]  
+     [-c <cell name>]  [-n]  [-l]  [-h]
+

Description +

The butc command initializes a Tape Coordinator process on a +Tape Coordinator machine, enabling an operator to direct Backup System +requests to the associated tape device or backup data file. (The Tape +Coordinator controls a backup data file if the FILE YES instruction +appears in the /usr/afs/backup/CFG_device_name file that +corresponds to the Tape Coordinator's entry in the +/usr/afs/backup/tapeconfig file. For the sake of simplicity, +the following discusses tape devices only.) +

It is conventional to start and run the Tape Coordinator in the +foreground. In this case, it runs on its own connection, which is +unavailable for any other use and must remain open the entire time the Tape +Coordinator is to accept backup requests and while it is executing +them. (When using a window manager, the connection corresponds to a +separate command shell window.) The Tape Coordinator can run in the +background if the CFG_device_name file is configured to +eliminate any need for the Tape Coordinator to prompt the operator. In +both the foreground and background, the Tape Coordinator writes operation +traces and other output to the standard output stream on the connection over +which it was started. Use the -debuglevel argument to +control the amount of information that appears. The Tape Coordinator +also writes traces and error messages to two files in the local +/usr/afs/backup directory: +

The TE_device_name file records problems that the Tape +Coordinator encounters as it executes backup operations. +
The TL_device_name file records a trace of operations +as well as the same errors written to the TE_device_name +file. +

The Tape Coordinator creates the files automatically as it +initializes. If there are existing files, the Tape Coordinator renames +them with a .old extension, overwriting the existing +.old files if they exist. It derives the +device_name part of the file names by stripping off the device +name's /dev/ prefix and replacing any other slashes with +underscores. For example, the files are called TE_rmt_4m and +TL_rmt_4m for a device called /dev/rmt/4m. +

By default, at the beginning of each operation the Tape Coordinator prompts +for the operator to insert the first tape into the drive and press +<Return>. To suppress this prompt, include the +-noautoquery flag on the command line or the instruction +AUTOQUERY NO in the +/usr/afs/backup/CFG_device_name file. When the +prompt is suppressed, the first required tape must be in the drive before a +backup command is issued. For subsequent tapes, the Tape +Coordinator uses its normal tape acquisition routine: if the +/usr/afs/backup/CFG_device_name file includes a +MOUNT instruction, the Tape Coordinator invokes the indicated +command; otherwise, it prompts the operator for the next tape. +

To stop the Tape Coordinator process, enter an interrupt signal such as +<Ctrl-c> over the dedicated connection (in the command shell +window). +

To cancel a backup operation that involves a tape before it +begins (assuming the initial tape prompt has not been suppressed), enter the +letter a (for abort) and press <Return> at +the Tape Coordinator's prompt for the first tape. +

Tape Coordinator operation depends on the correct configuration of certain +files, as described in the following list: +

The local /usr/afs/backup/tapeconfig file must include an entry +for the Tape Coordinator that specifies its device name and port offset +number, among other information; for details, see the +tapeconfig reference page. +
The port offset number recorded in the Tape Coordinator's entry in +the Backup Database must match the one in the tapeconfig +file. Create the Backup Database entry by using the backup +addhost command. +
The optional /usr/afs/backup/CFG_device_name file can +contain instructions for mounting and unmounting tapes automatically (when +using a tape stacker or jukebox, for instance) or automating other aspects of +the backup process. The device_name part of the name is +derived as described previously for the TE_device_name and +TL_device_name files. +

Cautions +

If the Tape Coordinator machine is an AIX machine, use the SMIT +utility to set the device's block size to 0 (zero), indicating variable +block size. Otherwise, tape devices attached to machines running other +operating systems sometimes cannot read tapes written on AIX machines. +For instructions, see the IBM AFS Administration Guide chapter +about configuring the Backup System. +

Options +

-port +

Specifies the port offset number of the Tape Coordinator to +initialize. +

-debuglevel +

Controls the amount and type of messages the Tape Coordinator displays on +the standard output stream. Provide one of three acceptable +values: +

0 to display the minimum level of detail required to describe +Tape Coordinator operations, including prompts for tapes, messages that +indicate the beginning and end of operations, and error messages. This +is the default value. +
1 to display the names of the volumes being dumped or restored +as well as the information displayed at level 0. +
2 to display all messages also being written to the +TL_device_name log file. +

-cell +

Names the cell in which the Tape Coordinator operates (the cell to which +the file server machines that house affected volumes belong). If this +argument is omitted, the Tape Coordinator runs in the local cell as defined in +the local /usr/vice/etc/ThisCell file. Do not combine this +flag with the -localauth argument. +

-noautoquery +

Suppresses the Tape Coordinator's prompt for insertion of the first +tape needed for an operation. The operator must insert the tape into +the drive before issuing the backup command that initializes the +operation. +

-localauth +

Constructs a server ticket using the server encryption key with the +highest key version number in the local +/usr/afs/etc/KeyFile. The butc command +interpreter presents the ticket, which never expires, to the Volume Server and +Volume Location Server to use in mutual authentication. +

Do not combine this argument with the -cell flag, and use it +only when logged on to a server machine as the local superuser +root; client machines do not have +/usr/afs/etc/KeyFile file. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command starts the Tape Coordinator with port offset +7 at debug level 1, meaning the Tape Coordinator reports +the names of volumes it is dumping or restoring. +

   % butc -port 7 -debuglevel 1
+   
+

Privilege Required +

The issuer must be listed in the /usr/afs/etc/UserList file on +every machine where the Backup Server or Volume Location (VL) Server is +running, and on every file server machine that houses a volume to be backed +up. If the -localauth flag is included, the issuer must +instead be logged on to the Tape Coordinator machine as the local superuser +root. In addition, the issuer must be able to read and write +to the log and configuration files in the local /usr/afs/backup +directory. +

Related Information +

TE_device_name +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf127.htm b/doc/html/AdminReference/auarf127.htm new file mode 100644 index 0000000..3cd35a8 --- /dev/null +++ b/doc/html/AdminReference/auarf127.htm @@ -0,0 +1,186 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

dlog

+ + +

Purpose +

Authenticates to the DCE Security Service +

Synopsis +

dlog [-principal <user name>]  [-cell <cell name>]  
+     [-password <user's password>]  [-servers <explicit list of servers>⁺]  
+     [-lifetime <ticket lifetime in hh[:mm[:ss]]>]  
+     [-setpag]  [-pipe]  [-help]
+    
+dlog [-pr <user name>]  [-c <cell name>]  [-pw <user's password>] 
+     [-ser <explicit list of servers>⁺]  
+     [-l <ticket lifetime in hh[:mm[:ss]]>]  [-set]  [-pi]  [-h]
+

Description +

The dlog command obtains DCE credentials for the issuer from the +DCE Security Service in the cell named by the -cell argument, and +stores them on the AFS client machine on which the user issues the +command. The AFS/DFS Migration Toolkit Protocol Translator processes +running on machines in the DCE cell accept the credentials, which enables the +user to access the DCE cell's filespace from the AFS client. The +user's identity in the local file system is unchanged. +

If the issuer does not provide the -principal argument, the +dlog command interpreter uses the user name under which the issuer +is logged into the local file system. Provide the DCE password for the +appropriate user name. As with the klog command, the +password does not cross the network in clear text (unless the issuer is logged +into the AFS client from a remote machine). +

The credentials are valid for a lifetime equivalent to the smallest of the +following, all but the last of which is defined by the DCE cell's +Security Server: +

The maximum certificate lifetime for the issuer's DCE account +
The maximum certificate lifetime for the afs principal's +DCE account +
The registry-wide maximum certificate lifetime +
The registry-wide default certificate lifetime +
The lifetime requested using the -lifetime argument +

If the previous maximum certificate lifetime values are set to +default-policy, the maximum possible ticket lifetime is defined by +the default certificate lifetime. Refer to the DCE vendor's +administration guide for more information before setting any of these +values. +

The AFS Cache Manager stores the ticket in a credential structure +associated with the name of the issuer (or the user named by the +-principal argument. If the user already has a ticket for +the DCE cell, the ticket resulting from this command replaces it in the +credential structure. +

The AFS tokens command displays the ticket obtained by the +dlog command for the server principal afs, regardless of +the principal to which it is actually granted. Note that the +tokens command does not distinguish tickets for a DFS^TM +File Server from tickets for an AFS File Server. +

Options +

-principal +

Specifies the DCE user name for which to obtain DCE credentials. If +this option is omitted, the dlog command interpreter uses the name +under which the issuer is logged into the local file system. +

-cell +

Specifies the DCE cell in which to authenticate. During a single +login session on a given machine, a user can authenticate in multiple cells +simultaneously, but can have only one ticket at a time for each cell (that is, +it is possible to authenticate under only one identity per cell per +machine). It is legal to abbreviate the cell name to the shortest form +that distinguishes it from the other cells listed in the +/usr/vice/etc/CellServDB file on the local client machine. +

If the issuer does not provide the -cell argument, the +dlog command attempts to authenticate with the DCE Security Server +for the cell defined by +

The value of the environment variable AFSCELL on the local AFS client +machine, if defined. The issuer can set the AFSCELL environment +variable to name the desired DCE cell. +
The cell name in the /usr/vice/etc/ThisCell file on the local +AFS client machine. The machine's administrator can place the +desired DCE cell's name in the file. +

-password +

Specifies the password for the issuer (or for the user named by the +-principal argument). Using this argument is not +recommended, because it makes the password visible on the command line. +If this argument is omitted, the command prompts for the password and does not +echo it visibly. +

-servers +

Specifies a list of DFS database server machines running the Translator +Server through which the AFS client machine can attempt to +authenticate. Specify each server by hostname, shortened machine name, +or IP address. If this argument is omitted, the dlog command +interpreter randomly selects a machine from the list of DFS Fileset Location +(FL) Servers in the /usr/vice/etc/CellServDB file for the DCE cell +specified by the -cell argument. This argument is useful for +testing when authentication seems to be failing on certain server +machines. +

-lifetime +

Requests a ticket lifetime using the format +hh:mm[:ss] +(hours, minutes, and optionally a number seconds between 00 and 59). +For example, the value 168:30 requests a ticket lifetime of 7 +days and 30 minutes, and 96:00 requests a lifetime of 4 +days. Acceptable values range from 00:05 (5 minutes) +to 720:00 (30 days). If this argument is not provided +and no other determinants of ticket lifetime have been changed from their +defaults, ticket lifetime is 10 hours. +

The requested lifetime must be smaller than any of the DCE cell's +determinants for ticket lifetime; see the discussion in the preceding +Description section. +

-setpag +

Creates a process authentication group (PAG) in which the newly created +ticket is placed. If this flag is omitted, the ticket is instead +associated with the issuers' local user ID (UID). +

-pipe +

Suppresses any prompts that the command interpreter otherwise produces, +including the prompt for the issuer's password. Instead, the +command interpreter accepts the password via the standard input stream. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

If the dlog command interpreter cannot contact a Translator +Server, it produces a message similar to the following: +

   dlog: server or network not responding -- failed to contact
+   authentication service
+   
+

Examples +

The following command authenticates the issuer as cell_admin in +the dce.abc.com cell. +

   % dlog -principal cell_admin -cell dce.abc.com
+   Password: cell_admin's password
+    
+

In the following example, the issuer authenticates as cell_admin +to the dce.abc.com cell and request a ticket lifetime +of 100 hours. The tokens command confirms that the user +obtained DCE credentials as the user cell_admin: the AFS ID +is equivalent to the UNIX ID of 1 assigned to cell_admin +in dce.abc.com cell's DCE registry. +

   % dlog -principal cell_admin -cell dce.abc.com -lifetime 100
+   Password: cell_admin's password
+   
+   % tokens
+   Tokens held by the Cache Manager:
+   
+   User's (AFS ID 1) tokens for afs@dce.abc.com [Expires Jul 6 14:12] 
+   User's (AFS ID 4758) tokens for afs@abc.com [Expires Jul 2 13:14] 
+ 
+      --End of list--
+   
+

Privilege Required +

None +

Related Information +

dpass +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf128.htm b/doc/html/AdminReference/auarf128.htm new file mode 100644 index 0000000..d1891c5 --- /dev/null +++ b/doc/html/AdminReference/auarf128.htm @@ -0,0 +1,114 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

dpass

+ + +

Purpose +

Returns the DCE password for a new DCE account +

Synopsis +

dpass [-cell <original AFS cell name>]  [-help] 
+  
+dpass [-c <original AFS cell name>]  [-h]
+

Description +

The dpass command returns the DCE password that an administrator +assigned to the issuer when using the dm pass command to migrate +AFS user accounts into a DCE cell. +

The dpass command, issued on an AFS client, requests the +issuer's new DCE password from the AFS cell specified with the +-cell argument. +

The issuer must be authenticated as the AFS user whose AFS account was +moved into DCE, and be able to provide the user's AFS password when +prompted by the dpass command. +

Options +

-cell +: Specifies the name of the AFS cell from which the AFS account was moved +into DCE and from which to fetch the new DCE password. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

By default, the dpass command writes a message similar to the +following to the standard output stream. +

   Please read the following message before entering your password.  
+    
+   This program will display your new, temporary DCE password on your
+   terminal, and you should change the assigned password as soon as 
+   possible (from a DCE client).  The program assumes that the AFS cell 
+   uses the AFS Authentication Server and that an administrator used the 
+   utilities in the AFS/DFS Migration Toolkit to migrate the account from 
+   AFS to DCE. The password you enter should be the AFS password that was 
+   in effect when your DCE account was created; this is not necessarily 
+   the same password you have at the moment.  The cell name (which you 
+   may override with a command line option), must be the name of the AFS 
+   cell from which the authentication information was taken.
+    
+

To suppress this message, set the DPASS_NO_MESSAGE environment +variable. It is then possible to substitute a customized message if +desired by using a script similar to the following example: +

   #! /bin/csh
+   echo "Start of customized message"
+   echo "Continuation of customized message"
+     .
+     .
+     .
+   echo "Conclusion of customized message"
+   setenv DPASS_NO_MESSAGE
+   dpass $*
+   
+

After the standard or customized message, if any, the dpass +command generates the following prompt for the original AFS password: +

   Original password for AFS cell cell:
+   Re-enter password to verify:
+   
+

If the AFS passwords match and are correct, the command reports the +temporary DCE password in the following message. +

   The new DCE password is: Issuer's_temporary_DCE_password
+    
+

Examples +

The following example returns the DCE password of the issuer, whose AFS +account is in the abc.com cell. The DPASS_NO_MESSAGE +variable has been set to suppress the standard message. +

   % dpass
+   Original password for AFS cell abc.com: Issuer's_AFS_password
+   Re-enter password to verify: Issuer's_AFS_password
+   The new DCE password is: 8655--eg8e-dcdc-8157
+   
+

Privilege Required +

The issuer must be authenticated as the AFS user for whom to display the +corresponding DCE password. +

Related Information +

dlog +

dm pass reference page in IBM AFS/DFS Migration Toolkit +Administration Guide and Reference +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf129.htm b/doc/html/AdminReference/auarf129.htm new file mode 100644 index 0000000..953049a --- /dev/null +++ b/doc/html/AdminReference/auarf129.htm @@ -0,0 +1,391 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fileserver

+ + + +

Purpose +

Initializes the File Server component of the fs process +

Synopsis +

fileserver [-d <debug level>]  [-p <number of processes>]
+           [-spare <number of spare blocks>]  
+           [-pctspare <percentage spare>]  [-b <buffers>]
+           [-l <large vnodes>]  [-s <small  nodes>]
+           [-vc <volume cachesize>]  [-w <call back wait interval>]
+           [-cb <number of call backs>]
+           [-banner (print banner every 10 minutes)]
+           [-novbc (whole volume cbs disabled)]
+           [-implicit <admin mode bits: rlidwka>]
+           [-hr <number of hours between refreshing the host cps>]
+           [-busyat <redirect clients when queue > n>]
+           [-rxpck <number of rx extra packets>]
+           [-rxdbg (enable rx debugging)]
+           [-rxdbge (enable rxevent debugging)]
+           [-m <min percentage spare in partition>]
+           [-lock (keep fileserver from swapping)]
+           [-L (large server conf)]  [-S (small server conf)]
+           [-k <stack size>]  [-realm <Kerberos realm name>]
+           [-udpsize <size of socket buffer in bytes>]  
+           [-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 fileserver command initializes the File Server component of +the fs process. In the conventional configuration, its +binary file is located in the /usr/afs/bin directory on a file +server machine. +

The fileserver command is not normally issued at the command +shell prompt, but rather placed into a database server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a file server machine as the local superuser +root. +

The File Server creates the /usr/afs/logs/FileLog log file as it +initializes, if the file does not already exist. It does not write a +detailed trace by default, but use the -d option to increase the +amount of detail. Use the bos getlog command to display the +contents of the log file. +

The command's arguments enable the administrator to control many +aspects of the File Server's performance, as detailed in the +Options section. By default the fileserver +command sets values for many arguments that are suitable for a medium-sized +file server machine. To set values suitable for a small or large file +server machine, use the -S or -L flag +respectively. The following list describes the parameters and +corresponding argument for which the fileserver command sets +default values, and Table 1 summarizes the setting for each of the three machine +sizes. +

The maximum number of lightweight processes (LWPs) the File Server uses to +handle requests for data; corresponds to the -p +argument. The File Server always uses a minimum of 32 KB for these +processes. +
The maximum number of directory blocks the File Server caches in +memory; corresponds to the -b argument. Each cached +directory block (buffer) consumes 2,092 bytes of memory. +
The maximum number of large vnodes the File Server caches in memory for +tracking directory elements; corresponds to the -l +argument. Each large vnode consumes 292 bytes of memory. +
The maximum number of small vnodes the File Server caches in memory for +tracking file elements; corresponds to the -s argument. +Each small vnode consumes 100 bytes of memory. +
The maximum volume cache size, which determines how many volumes the File +Server can cache in memory before having to retrieve data from disk; +corresponds to the -vc argument. +
The maximum number of callback structures the File Server caches in +memory; corresponds to the -cb argument. Each callback +structure consumes 16 bytes of memory. +
The maximum number of Rx packets the File Server uses; +corresponds to the -rxpck argument. Each packet consumes +1544 bytes of memory. +

+
+

Table 1. File Server configuration parameters
+ + + + + + + + + +
Parameter (Argument) + Small configuration (-S) + Medium configuration (default) + Large configuration (-L) +
Number of LWPs (-p) + 6 + 9 + 12 +
Number of cached directory blocks (-b) + 70 + 90 + 120 +
Number of cached large vnodes (-l) + 200 + 400 + 600 +
Number of cached small vnodes (-s) + 200 + 400 + 600 +
Maximum volume cache size (-vc) + 200 + 400 + 600 +
Number of callbacks (-cb) + 20,000 + 60,000 + 64,000 +
Number of Rx packets (-rxpck) + 100 + 150 + 200 +
+

To override any of the values, provide the indicated argument (which can be +combined with the -S or -L flag). +

The amount of memory required for the File Server varies. The +approximate default memory usage is 751 KB when the -S flag is used +(small configuration), 1.1 MB when all defaults are used (medium +configuration), and 1.4 MB when the -L flag is used (large +configuration). If additional memory is available, increasing the value +of the -cb and -vc arguments can improve File Server +performance most directly. +

By default, the File Server allows a volume to exceed its quota by 1 MB +when an application is writing data to an existing file in a volume that is +full. The File Server still does not allow users to create new files in +a full volume. To change the default, use one of the following +arguments: + +

Set the -spare argument to the number of extra kilobytes that +the File Server allows as overage. A value of 0 allows no +overage. +
Set the -pctspare argument to the percentage of the +volume's quota the File Server allows as overage. +

By default, the File Server implicitly grants the a +(administer) and l (lookup) permissions to +the system:administrators on the access control list (ACL) of +every directory in the volumes stored on its file server machine. In +other words, the group's members can exercise those two permissions even +when an entry for the group does not appear on an ACL. To change the +set of default permissions, use the -implicit argument. +

The File Server maintains a host current protection subgroup +(host CPS) for each client machine from which it has received a +data access request. Like the CPS for a user, a host CPS lists all of +the Protection Database groups to which the machine belongs, and the File +Server compares the host CPS to a directory's ACL to determine in what +manner users on the machine are authorized to access the directory's +contents. When the pts adduser or pts removeuser +command is used to change the groups to which a machine belongs, the File +Server must recompute the machine's host CPS in order to notice the +change. By default, the File Server contacts the Protection Server +every two hours to recompute host CPSs, implying that it can take that long +for changed group memberships to become effective. To change this +frequency, use the -hr argument. +
Note: The AIX operating system does not automatically reserve a part of each +partition to avoid the negative consequences that can result when the space on +a partition is completely exhausted. Therefore, the AIX version of the +File Server creates an 8% disk reserve automatically. To change the +percentage, use the -m argument. +
+

The File Server generates the following message when a partition is nearly +full: +

   No space left on device
+   
+

Cautions +

Do not use the -k and -w arguments, which are +intended for use by the AFS Development group only. Changing them from +their default values can result in unpredictable File Server behavior. +In any case, on many operating systems the File Server uses native threads +rather than the LWP threads, so using the -k argument to set the +number of LWP threads has no effect. +

Do not specify both the -spare and -pctspare +arguments. Doing so causes the File Server to exit, leaving an error +message in the /usr/afs/logs/FileLog file. +

Options that are available only on some system types, such as the +-m and -lock options, appear in the output generated by +the -help option only on the relevant system type. +

Options +

-d +

Sets the detail level for the debugging trace written to the +/usr/afs/logs/FileLog file. Provide one of the following +values, each of which produces an increasingly detailed trace: +0, 1, 5, 25, and +125. The default value of 0 produces only a few +messages. +

-p +

Sets the number of threads to run. Provide a positive +integer. The File Server creates and uses five threads for special +purposes, in addition to the number specified (but if this argument specifies +the maximum possible number, the File Server automatically uses five of the +threads for its own purposes). +

The maximum number of threads can differ in each release of AFS. +Consult the IBM AFS Release Notes for the current release. +

-spare +

Specifies the number of additional kilobytes an application can store in a +volume after the quota is exceeded. Provide a positive integer; a +value of 0 prevents the volume from ever exceeding its +quota. Do not combine this argument with the -pctspare +argument. +

-pctspare +

Specifies the amount by which the File Server allows a volume to exceed +its quota, as a percentage of the quota. Provide an integer between +0 and 99. A value of 0 prevents the +volume from ever exceeding its quota. Do not combine this argument with +the -spare argument. +

-b +

Sets the number of directory buffers. Provide a positive +integer. +

-l +

Sets the number of large vnodes available in memory for caching directory +elements. Provide a positive integer. +

-s +

Sets the number of small vnodes available in memory for caching file +elements. Provide a positive integer. +

-vc +

Sets the number of volumes the File Server can cache in memory. +Provide a positive integer. +

-w +

Sets the interval at which the daemon spawned by the File Server performs +its maintenance tasks. Do not use this argument; changing the +default value can cause unpredictable behavior. +

-cb +

Sets the number of callbacks the File Server can track. Provide a +positive integer. +

-banner +

Prints the following banner to /dev/console about every 10 +minutes. +

   File Server is running at time.
+   
+

-novbc +

Prevents the File Server from breaking the callbacks that Cache Managers +hold on a volume that the File Server is reattaching after the volume was +offline (as a result of the vos restore command, for +example). Use of this flag is strongly discouraged. +

-implicit +

Defines the set of permissions granted by default to the +system:administrators group on the ACL of every directory in +a volume stored on the file server machine. Provide one or more of the +standard permission letters (rlidwka) and auxiliary permission +letters (ABCDEFGH), or one of the shorthand notations for groups of +permissions (all, none, read, and +write). To review the meaning of the permissions, see the +fs setacl reference page. +

Note:

The File Server always implicitly grants the a permission to the +system:administrators group, even if you use the +none value. +

-hr +

Specifies how often the File Server refreshes its knowledge of the +machines that belong to protection groups (refreshes the host CPSs for +machines). The File Server must update this information to enable users +from machines recently added to protection groups to access data for which +those machines now have the necessary ACL permissions. +

-busyat +

Defines the number of incoming RPCs that can be waiting for a response +from the File Server before the File Server returns the error code +VBUSY to the Cache Manager that sent the latest RPC. In +response, the Cache Manager retransmits the RPC after a delay. This +argument prevents the accumulation of so many waiting RPCs that the File +Server can never process them all. Provide a positive integer. +The default value is 600. +

-rxpck +

Controls the number of Rx packets the File Server uses to store data for +incoming RPCs that it is currently handling, that are waiting for a response, +and for replies that are not yet complete. Provide a positive +integer. +

-rxdbg +

Writes a trace of the File Server's operations on Rx packets to the +file /usr/afs/logs/rx_dbg. +

-rxdbge +

Writes a trace of the File Server's operations on Rx events (such as +retransmissions) to the file /usr/afs/logs/rx_dbg. +

-m +

Specifies the percentage of each AFS server partition that the AIX version +of the File Server creates as a reserve. Specify an integer value +between 0 and 30; the default is 8%. A value +of 0 means that the partition can become completely full, which can +have serious negative consequences. +

Note:

This argument is available only on machines running the AIX operating system, +and so does not appear in the syntax statement when the -help flag +is used on other system types. +

-lock +

Prevents any portion of the fileserver binary from being paged +(swapped) out of memory on a file server machine running the IRIX operating +system. +

Note:

This argument is available only on machines running the IRIX operating +system, and so does not appear in the syntax statement when the +-help flag is used on other system types. +

-L +

Sets values for many arguments in a manner suitable for a large file +server machine. Combine this flag with any option except the +-S flag; omit both flags to set values suitable for a +medium-sized file server machine. +

-S +

Sets values for many arguments in a manner suitable for a small file +server machine. Combine this flag with any option except the +-L flag; omit both flags to set values suitable for a +medium-sized file server machine. +

-k +

Sets the LWP stack size in units of 1 kilobyte. Do not use this +argument, and in particular do not specify a value less than the default of +24. +

-realm +

Defines the Kerberos realm name for the File Server to use. If this +argument is not provided, it uses the realm name corresponding to the cell +listed in the local /usr/afs/etc/ThisCell file. +

-udpsize +

Sets the size of the UDP buffer, which is 64 KB by default. Provide +a positive integer, preferably larger than the default. +

-enable_peer_stats +

-enable_process_stats +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following bos create command creates an fs +process on the file server machine fs2.abc.com that +uses the large configuration size, and allows volumes to exceed their quota by +10%. Type the command on a single line: +

   % bos create -server fs2.abc.com -instance fs -type fs   \ 
+                -cmd "/usr/afs/bin/fileserver -pctspare 10 \
+                -L" /usr/afs/bin/volserver /usr/afs/bin/salvager
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf130.htm b/doc/html/AdminReference/auarf130.htm new file mode 100644 index 0000000..ceeb4b6 --- /dev/null +++ b/doc/html/AdminReference/auarf130.htm @@ -0,0 +1,140 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fms

+ + + + + + + + + + +

Purpose +

Determine a tape's capacity and a tape device's filemark size +

Synopsis +

fms -tape <tape special file>  [-help]
+    
+fms  -t <tape special file>  [-h]
+

Description +

The fms command determines the capacity of the tape currently in +the tape device identified by the -tape argument, along with the +size of the filemark for the device. The filemark is also referred to +as the device's end-of-file (EOF) marker, and can differ for each +combination of tape and tape device. +

As the Tape Coordinator writes a dump, it writes a filemark between the +data included from each volume and also tracks the amount of space left before +the end of the tape (EOT). For some tape devices, the filemark is large +enough (multiple megabytes) that failure to consider it leads the Tape +Coordinator significantly to overestimate the available space. +

The intended use of this command is to determine tape capacity and filemark +size values that can be specified in a tape device's entry in the +/usr/afs/backup/tapeconfig file. For certain types of tape +drives, the Tape Coordinator operates more efficiently when the +tapeconfig file lists accurate values. For further +discussion, see the IBM AFS Administration Guide chapter on +configuring the Backup System. +

Insert a tape in the drive before issuing this command. +

Cautions +

Do not use this command on compressing tape devices in compression mode or +with tape devices that handle tapes of multigigabyte (or multiterabyte) +capacity. It does not produce accurate results in those cases. +For alternate suggestions on the values to record in the tapeconfig +file for compressing drives, see the IBM AFS Administration Guide +chapter on configuring the Backup System. +

Running the command completely overwrites the tape, so use a blank one or +one that can be recycled. +

Because it writes filemarks to the complete length of the tape, the command +can take from several hours to more than a day to complete. +

Options +

-tape +: Specifies the UNIX device name of the tape device for which to determine +filemark size and the capacity of the tape it currently contains. The +format varies on different system types, but usually begins with +/dev; an example is /dev/sd0a. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The command generates output both on the standard output stream and in the +fms.log file that it creates in the current working +directory. The output reports the capacity of the tape in the device +and the device's filemark size. +

The first few lines of output include status information about the +execution of the command, including such information as the number of blocks +and the number of file marks written to the tape by the command. The +last two lines of both screen and file output provide the following +information: +

Tape capacity is number bytes: +specifies the size, in bytes, of the tape in the device. +
File marks are number bytes: +specifies the device's filemark size in bytes. +

The following message indicates that the fms command interpreter +cannot access the tape device. The command halts. +

   Can't open tape drive device
+   
+

The following message indicates that the command interpreter cannot create +the fms.log log file. Again, the command +halts. +

   Can't open log file
+   
+

Examples +

The following command illustrates the output for the device called +/dev/rmt1h: +

   % fms /dev/rmt1h
+   wrote block: 130408
+   Finished data capacity test - rewinding
+   wrote 1109 blocks, 1109 file marks
+   Finished file mark test
+   Tape capacity is 2136604672 bytes
+   File marks are 1910205 bytes
+   
+

The following appears in the fms.log file: +

   fms test started
+   wrote 9230 blocks
+   Finished file mark test
+   Tape capacity is 151224320 bytes
+   File marks are 2375680 bytes
+   
+

Privilege Required +

The issuer must be able to insert and write to files in the currently +working directory, if the fms.log file does not already +exist. If it already exists, the issuer need only be able to write to +it. +

Related Information +

fms.log +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf131.htm b/doc/html/AdminReference/auarf131.htm new file mode 100644 index 0000000..6964fa2 --- /dev/null +++ b/doc/html/AdminReference/auarf131.htm @@ -0,0 +1,169 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs

+ + + + + +

Purpose +

Introduction to the fs command suite +

Description +

The commands in the fs command suite constitute the main +administrative interface to the Cache Manager on an AFS client machine, which +is responsible for fetching AFS data from file server machines on behalf of +applications running on the client machine. +

There are several categories of commands in the fs command +suite: +

Commands to set and report how the Cache Manager interacts with server +machines: fs checkservers, fs getcellstatus, +fs getserverprefs, fs listcells, fs newcell, +fs setcell, +
fs setserverprefs, fs sysname, and fs +wscell +
Commands to administer access control lists (ACLs): fs +cleanacl, fs copyacl, fs listacl, and fs +setacl +
Commands to administer server machines, volumes or partitions that house a +given file or directory: fs diskfree, fs examine, +fs listquota, fs quota, fs setquota, fs +setvol, +
fs whereis, and fs whichcell +
Commands to administer the local client cache and related +information: fs checkvolumes, fs flush, fs +flushvolume, fs getcacheparms, and fs setcachesize +
Commands to administer volume mount points: fs lsmount, +fs mkmount, and fs rmmount +
Commands to control monitoring and tracing: fs debug, and +fs messages +
A command to administer the Cache Manager's interaction with other +file systems: fs exportafs +
Commands to obtain help: fs apropos and fs +help +

The Cache Manager and the fs commands use and maintain the +following configuration files: +

The /usr/vice/etc/CellServDB file lists the database server +machines in the local cell and any foreign cell to which the administrator +wishes to enable AFS access for users working on the machine. The +database server machines run the Authentication, Backup, Protection and Volume +Location (VL) Server processes, which maintain databases of administrative +information. For users to access a cell, its +root.cell volume must also be mounted in the local +cell's AFS file tree. +
The /usr/vice/etc/ThisCell file defines the machine's cell +membership with respect to the AFS command suites and Cache Manager access to +AFS data. +
The /usr/vice/etc/cacheinfo file defines configuration +parameters for the cache, including its size and whether it is in memory or on +disk. +

In addition, the Cache Manager automatically creates files on the cache +partition (by default, /usr/vice/cache for caching and tracking +files fetched from file server machines. +

For more details, see the reference page for each file. +

Options +

The following flag is available on every command in the fs +suite. The reference page for each command also lists it, but it is +described here in greater detail. + + + +

-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. +

Privilege Required + + +

The privileges required for fs commands vary more than for other +command suites. Pay special attention to the Privilege +Required section of each command description. +

The various types of necessary privilege include: +

Having permissions on a directory's ACL. For example, creating +and removing mount points requires a (administer), +i (insert), and d (delete) +permissions on the ACL of the directory in which the mount point +resides. +
Being logged onto the machine as the local superuser +root. This is necessary when issuing commands that affect +Cache Manager configuration. +
Belonging to the system:administrators group in the +Protection Database. +
No privilege. Many fs commands simply list +information. +

Related Information +

Vn +

fs help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf132.htm b/doc/html/AdminReference/auarf132.htm new file mode 100644 index 0000000..58a0d6d --- /dev/null +++ b/doc/html/AdminReference/auarf132.htm @@ -0,0 +1,73 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs apropos

+ + + +

Purpose +

Displays each help entry containing a keyword string +

Synopsis +

fs apropos -topic <help string>  [-help]
+   
+fs ap -t <help string>  [-h]
+

Description +

The fs apropos command displays the first line of the online +help entry for any fs 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 fs 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 +fs command where the string specified with the -topic +argument is part of the command name or first line. +

Examples +

The following command lists all fs commands that include the +word cache in their names or short online descriptions: +

   % fs apropos cache
+   setcachesize: set cache size
+   flush: flush file from cache
+   getcacheparms: get cache usage info
+   monitor: set cache monitor host address
+   
+

Privilege Required +

None +

Related Information +

fs +

fs help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf133.htm b/doc/html/AdminReference/auarf133.htm new file mode 100644 index 0000000..793e898 --- /dev/null +++ b/doc/html/AdminReference/auarf133.htm @@ -0,0 +1,197 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs checkservers

+ + + + + + + + +

Purpose +

Displays the status of server machines +

Synopsis +

fs checkservers [-cell <cell to check>]  [-all]  [-fast]  
+                [-interval <seconds between probes>]  [-help]
+   
+fs checks [-c <cell to check>]  [-a]  [-f]  
+          [-i <seconds between probes>]  [-h]
+

Description +

The fs checkservers command reports whether certain AFS server +machines are accessible from the local client machine. The machines +belong to one of two classes, and the Cache Manager maintains a list of them +in kernel memory: +

The database server machines in every cell listed in the local +/usr/vice/etc/CellServDB file, plus any machines added to the +memory list by the fs newcell command since the last reboot. +
All file server machines the Cache Manager has recently contacted, and +which it probably needs to contact again soon. In most cases, the Cache +Manager holds a callback on a file or volume fetched from the machine. +

If the Cache Manager is unable to contact the vlserver process +on a database server machine or the fileserver process on a file +server machine, it marks the machine as inaccessible. (Actually, if a +file server machine is multihomed, the Cache Manager attempts to contact all +of the machine's interfaces, and only marks the machine as down if the +fileserver fails to reply via any of them.) The Cache +Manager then periodically (by default, every three minutes) sends a probe to +each marked machine, to see if it is still inaccessible. If a +previously inaccessible machine responds, the Cache Manager marks it as +accessible and no longer sends the periodic probes to it. +

The fs checkservers command updates the list of inaccessible +machines by having the Cache Manager probe a specified set of them: +

By default, only machines that are marked inaccessible and belong to the +local cell (the cell listed in the local /usr/vice/etc/ThisCell +file) +
If the -cell argument is included, only machines that are +marked inaccessible and belong to the specified cell +
If the -all flag is included, all machines marked inaccessible +

If the -fast flag is included, the Cache Manager does not probe +any machines, but instead reports the results of the most recent previous +probe. +

To set the interval between probes rather than produce a list of +inaccessible machines, use the -interval argument. The +non-default setting persists until the machine reboots; to preserve it +across reboots, put the appropriate fs checkservers command in the +machine's AFS initialization files. +

Cautions +

The command can take quite a while to complete, if a number of machines do +not respond to the Cache Manager's probe. The Cache Manager probes +machines sequentially and waits a standard timeout period before marking the +machine as unresponsive, to allow for slow network communication. To +make the command shell prompt return quickly, put the command in the +background. It is harmless to interrupt the command by typing +Ctrl-c or another interrupt signal. +

Note that the Cache Manager probes only server machines marked inaccessible +in its memory list. A server machine's absence from the output +does not necessarily mean that it is functioning, because it possibly is not +included in the memory list at all (if, for example, the Cache Manager has not +contacted it recently). For the same reason, the output is likely to +vary on different client machines. +

Unlike most fs commands, the fs checkservers command +does not refer to the AFSCELL environment variable. +

Options +

-cell +

Names each cell in which to probe server machines marked as +inaccessible. Provide the fully qualified domain name, or a shortened +form that disambiguates it from the other cells listed in the local +/usr/vice/etc/CellServDB file. Combine this argument with +the -fast flag if desired, but not with the -all +flag. Omit both this argument and the -all flag to probe +machines in the local cell only. +

-all +

Probes all machines in the Cache Manager's memory list that are +marked inaccessible. Combine this argument with the -fast +flag if desired, but not with the -cell argument. Omit both +this flag and the -cell argument to probe machines in the local +cell only. +

-fast +

Displays the Cache Manager's current list of machines that are +inaccessible, rather than sending new probes. The output can as old as +the current setting of the probe interval (by default three minutes, and +maximum ten minutes). +

-interval +

Sets or reports the number of seconds between the Cache Manager's +probes to machines in the memory list that are marked inaccessible: +

To set the interval, specify a value from the range between 1 +and 600 (10 minutes); the default is 180 (three +minutes). The issuer must be logged in as the local superuser +root. The altered setting persists until again changed with +this command, or until the machine reboots, at which time the setting returns +to the default. +
Provide a value of 0 (zero) to display the current interval +setting. No privilege is required. Do not combine this argument +with any other. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

If there are no machines marked as inaccessible, or if all of them now +respond to the Cache Manager's probe, the output is: +

   All servers are running.
+   
+

Note that this message does not mean that all server machines in each +relevant cell are running. The output indicates the status of only +those machines that the Cache Manager probes. +

If a machine fails to respond to the probe within the timeout period, the +output begins with the string +

   These servers unavailable due to network or server problems:
+   
+

and lists the hostname of each machine on its own line. The Cache +Manager stores machine records by Internet address, so the format of each +hostname (uppercase or lowercase letters, or an Internet address in dotted +decimal format) depends on how the local cell's name service translates +it at the time the command is issued. If a server machine is +multihomed, the output lists only one of its interfaces (usually, the +currently most preferred one). +

If the -interval argument is provided with a value between +1 and 600, there is no output. If the value is +0, the output reports the probe interval as follows: +

   The current down server probe interval is interval secs
+   
+

Examples +

The following command displays the Cache Manager's current list of +unresponsive machines in the local cell, rather than probing them +again. The output indicates that if there were any machines marked +inaccessible, they all responded to the previous probe. +

   % fs checkservers -fast
+   All servers are running.
+   
+

The following example probes machines in the Cache Manager's memory +list that belong to the stateu.edu cell: +

   % fs checkservers -cell stateu.edu
+   All servers are running.
+   
+

The following example probes all server machines in the Cache +Manager's memory list. It reports that two machines did not +respond to the probe. +

   % fs checkservers -all
+   These servers unavailable due to network or server problems:
+   fs1.abc.com SV3.STATE.EDU.
+   
+

Privilege Required +

To set the probe interval, the issuer must be logged in as the local +superuser root. Otherwise, no privilege is required. +

Related Information +

fs newcell +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf134.htm b/doc/html/AdminReference/auarf134.htm new file mode 100644 index 0000000..9019a4c --- /dev/null +++ b/doc/html/AdminReference/auarf134.htm @@ -0,0 +1,69 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs checkvolumes

+ + + + + + + + + + +

Purpose +

Forces the Cache Manager to update volume-related information +

Synopsis +

fs checkvolumes [-help]
+   
+fs checkv [-h]
+

Description +

The fs checkvolumes command discards the table of mappings +between volume names and volume ID numbers that the Cache Manager stores in +memory and uses when fetching data from volumes. The next time an +application requests AFS data, the Cache Manager must contact the Volume +Location (VL) Server for volume location information, and then an appropriate +file server machine for the actual data. +

The Cache Manager updates the table of mappings periodically (by default, +hourly), but this command is useful if the issuer knows that a volume's +name has changed, or that new read-only replicas of a volume have been +released, because issuing it forces the Cache Manager to reference the changed +volume. +

Options +

-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The following message confirms that the command ran successfully. +

   All volumeID/name mappings checked.
+   
+

Privilege Required +

None +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf135.htm b/doc/html/AdminReference/auarf135.htm new file mode 100644 index 0000000..a6a2bf9 --- /dev/null +++ b/doc/html/AdminReference/auarf135.htm @@ -0,0 +1,108 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs cleanacl

+ + + + + + + +

Purpose +

Remove obsolete entries from an ACL +

Synopsis +

fs cleanacl [-path <dir/file path>⁺]  [-help]
+   
+fs cl [-p <dir/file path>⁺]  [-h] 
+

Description +

The fs cleanacl command removes from the access control list +(ACL) of each specified directory or file any entry that refers to a user or +group that no longer has a Protection Database entry. Such an entry +appears on the ACL as an AFS user ID number (UID) rather than a name, because +without a Protection Database entry, the File Server cannot translate the UID +into a name. +

Cleaning access control lists in this way not only keeps them from becoming +crowded with irrelevant information, but also prevents the new possessor of a +recycled AFS UID from obtaining access intended for the former possessor of +the AFS UID. (Note that recycling UIDs is not recommended in any +case.) +

Options +

-path +

Names each directory for which to clean the ACL (specifying a filename +cleans its directory's ACL). If this argument is omitted, the +current working directory's ACL is cleaned. +

Specify the read/write path to each directory, to avoid the failure that +results from attempting to change 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 +fs mkmount reference page. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

If there are no obsolete entries on the ACL, the following message +appears: +

   Access list for dir/file path is fine.
+   
+

Otherwise, the output reports the resulting state of the ACL, following the +header +

   Access list for dir/file path is now
+   
+

At the same time, the following error message appears for each file in the +cleaned directories: +

   fs: 'filename': Not a directory
+   
+

Examples +

The following example illustrates the cleaning of the ACLs on the current +working directory and two of its subdirectories. Only the second +subdirectory had obsolete entries on it. +

   % fs cleanacl -path . ./reports ./sources
+   Access list for . is fine.
+   Access list for ./reports is fine.
+   Access list for ./sources is now
+   Normal rights:
+      system:authuser rl
+      pat rlidwka
+   
+

Privilege Required +

The issuer must have the a (administer) permission on +each directory's ACL (or the ACL of each file's parent +directory); the directory's owner and the members of the +system:administrators group have the right implicitly, even +if it does not appear on the ACL. +

Related Information +

fs listacl +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf136.htm b/doc/html/AdminReference/auarf136.htm new file mode 100644 index 0000000..932dfdc --- /dev/null +++ b/doc/html/AdminReference/auarf136.htm @@ -0,0 +1,156 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs copyacl

+ + + + +

Purpose +

Copies an ACL from one directory to one or more other directories +

Synopsis +

fs copyacl -fromdir <source directory (or DFS file)>  
+           -todir <destination directory (or DFS file)>⁺  
+           [-clear]  [-id]  [-if]  [-help]
+   
+fs co -f <source directory (or DFS file)>  
+      -t <destination directory (or DFS file)>⁺  
+      [-c]  [-id]  [-if]  [-h]
+

Description +

The fs copyacl command copies the access control list (ACL) from +a source directory to each specified destination directory. The source +directory's ACL is unchanged, and changes to the destination +directory's ACL obey the following rules: +

If an entry on the source ACL does not already exist on the destination +ACL, it is added. +
If an entry exists on both the source and destination ACLs, the +permissions from the source ACL entry replace the current permissions on the +destination ACL entry. +
If an entry on the destination ACL has no corresponding entry on the +source ACL, it is removed if the -clear flag is included and is +unchanged otherwise. In other words, if the -clear flag is +provided, the source ACL completely replaces the destination ACL. +

When using this command to copy ACLs between objects in DFS filespace +accessed via the AFS/DFS Migration Toolkit Protocol Translator, it is possible +to specify files, as well as directories, with the -fromdir and +-todir arguments. For more information on copying ACLs +between DFS directories and files, refer to the IBM AFS/DFS Migration +Toolkit Administration Guide and Reference. +

Cautions +

Do not copy ACLs between AFS and DFS files or directories. The ACL +formats are incompatible. +

Options +

-fromdir +

Specifies the source directory from which to copy the ACL. +(Specifying an AFS file copies its directory's ACL, but specifying a DFS +file copies its own ACL). A partial pathname is interpreted relative to +the current working directory. +

-todir +

Specifies each directory for which to alter the ACL to match the source +ACL. (Specifying an AFS file halts the command with an error, but +specifying a DFS file alters the file's ACL). A partial pathname +is interpreted relative to the current working directory. +

Specify the read/write path to each directory (or DFS file), to avoid the +failure that results from attempting to change 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 +fs mkmount reference page. +

-clear +

Replaces the ACL of each destination directory with the source ACL. +

-id +

Modifies the Initial Container ACL of each DFS directory named by the +-todir argument, rather than the regular Object ACL. This +argument is supported only when both the source and each destination directory +reside in DFS and are accessed via the AFS/DFS Migration Toolkit Protocol +Translator. +

-if +

Modifies the Initial Object ACL of each DFS directory named by the +-todir argument, rather than the regular Object ACL. This +argument is supported only when both the source and each destination directory +reside in DFS and are accessed via the AFS/DFS Migration Toolkit Protocol +Translator. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example command copies the current working directory's +ACL to its subdirectory called reports. Note that the source +directory's ACL is unaffected. Entries on the reports +directory's that are not on the source ACL of the current directory +remain unaffected as well, because the -clear flag is not +used. +

   % fs listacl . reports
+   Access list for . is
+   Normal rights:
+      pat rlidwka
+      smith rlidwk
+   Access list for reports is
+   Normal rights:
+      pat rl
+      pat:friends rl
+   Negative rights
+      jones rlidwka
+   
+   % fs copyacl -fromdir . -todir reports
+   
+   % fs listacl . reports
+   Access list for . is
+   Normal rights:
+      pat rlidwka
+      smith rlidwk
+   Access list for reports is
+   Normal rights:
+      pat rlidwka
+      pat:friends rl
+      smith rlidwk
+   Negative rights
+      jones rlidwka
+   
+

Privilege Required +

To copy an ACL between AFS objects, the issuer must have the l +(lookup)) permission on the source directory's ACL and the +a (administer) permission on each destination +directory's ACL. If the -fromdir argument names a file +rather than a directory, the issuer must have both the l and +r (read) permissions on the ACL of the file's +directory. +

To copy an ACL between DFS objects, the issuer must have the r +permission on the source directory or file's ACL and the c +(control) permission on each destination directory or file's +ACL. +

Related Information +

fs listacl +

fs setacl +

IBM AFS/DFS Migration Toolkit Administration Guide and Reference +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf137.htm b/doc/html/AdminReference/auarf137.htm new file mode 100644 index 0000000..e4503e5 --- /dev/null +++ b/doc/html/AdminReference/auarf137.htm @@ -0,0 +1,119 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs diskfree

+ + + + + + + + + + + + + + + +

Purpose +

Displays information about the partition housing a directory or file +

Synopsis +

fs diskfree [-path <dir/file path>⁺]  [-help]
+   
+fs df [-p <dir/file path>⁺]  [-h]
+   
+fs di [-p <dir/file path>⁺]  [-h]
+

Description +

The fs diskfree command formats and displays information about +the partition that houses the volume containing the specified directory or +file, including its size and how much space is currently used. +

To display information about the volume itself, use the fs +examine command. The fs examine and fs +quota commands also display information about a volume. +

Cautions +

The partition-related statistics in this command's output do not +always agree with the corresponding values in the output of the standard UNIX +df command. The statistics reported by this command can be +up to five minutes old, because the Cache Manager polls the File Server for +partition information at that frequency. Also, on some operating +systems, the df command's report of partition size includes +reserved space not included in this command's calculation, and so is +likely to be about 10% larger. +

Options +

-path +: Names a file or directory that resides on the partition about which to +produce output. Partial pathnames are interpreted relative to the +current working directory, which is also the default value if this argument is +omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output reports the following information about the volume and partition +that houses each file or directory: +

Volume Name +: The name of the volume +
kbytes +: The partition's total size in kilobytes +
used +: The number of kilobytes used on the partition +
avail +: The number of kilobytes available on the partition +
%used +: The percentage of the partition's total space that is used (the +used statistic divided by the kbytes statistic, times +100) +

If the %used statistic is greater than 90%, it is marked with +the string <<WARNING at the right margin. +

If the volume is a read-only volume, the output includes information about +only one of the partitions that houses it, generally the one on the file +server machine with the lowest preference rank. To verify which machine +the output is referring to, use the vos listvldb command to list +the volume's locations, and the vos partinfo command to +display the size of each one. +

Examples +

The following example shows the output for the partitions housing the +volumes user.smith and sun4x_56.bin: +

   % fs diskfree -path /afs/abc.com/usr/smith /afs/abc.com/sun4x_56/bin
+   Volume Name     kbytes  used     avail     %used     
+   user.smith     4177920 3841258  336662       92% <<WARNING
+   sun4x_56.bin   4423680 3174500 1249180       72%
+   
+

Privilege Required +

The issuer must have the l (lookup) permission on the +ACL of the root directory of the volume that houses the file or directory +named by the -path argument, and on the ACL of each directory that +precedes it in the pathname. +

Related Information +

fs examine +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf138.htm b/doc/html/AdminReference/auarf138.htm new file mode 100644 index 0000000..74b2da8 --- /dev/null +++ b/doc/html/AdminReference/auarf138.htm @@ -0,0 +1,136 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs examine

+ + + + + + + + + + + + + + + + + + + + + + + + +

Purpose +

Displays information about the volume containing a directory or file +

Synopsis +

fs examine [-path <dir/file path>⁺]  [-help]
+   
+fs exa [-p <dir/file path>⁺]  [-h] 
+         
+fs listvol [-p <dir/file path>⁺]  [-h] 
+     
+fs listv [-p <dir/file path>⁺]  [-h] 
+        
+fs lv [-p <dir/file path>⁺]  [-h]
+

Description +

The fs examine command displays information about the volume +containing each specified directory or file, including its volume ID number, +quota and the percentage of its quota that is used. +

This command provides the most information about a volume, but the fs +listquota command displays similar information in tabular format, and +the fs quota command reports only the percentage of quota +used. +

To set volume quota, use the fs setquota or fs setvol +command. +

Cautions +

Options +

-path +: Names a file or directory that resides in the volume about which to +produce output. Partial pathnames are interpreted relative to the +current working directory, which is also the default value if this argument is +omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output displays information about the volume that houses each specified +directory or file, in the following format +

   Volume status for vid = volume ID named volume name
+   Current offline message is message
+   Current disk quota is quota in kilobytes
+   Current blocks used are volume size in kilobytes
+   The partition has available partition blocks available out of
+      partition size
+   
+

where the first line specifies the volume's ID number and name. +The Current offline message line appears only +if an administrator has included the -offlinemsg argument to the +fs setvol command. The remaining lines report, respectively, +

the volume's quota in kilobytes, or the string unlimited +to indicate an unlimited quota +
the volume's current size in kilobytes +
the number of blocks available and total size of the host partition, both +in kilobytes. +

Examples +

The following example shows the output for the volume +user.smith and the partition housing it: +

   % fs examine -path /afs/abc.com/usr/smith
+   Volume status for vid = 50489902 named user.smith
+   Current maximum quota is 15000
+   Current blocks used are 5073
+   The partition has 336662 blocks available out of 4177920 
+   
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf139.htm b/doc/html/AdminReference/auarf139.htm new file mode 100644 index 0000000..b999ebb --- /dev/null +++ b/doc/html/AdminReference/auarf139.htm @@ -0,0 +1,199 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs exportafs

+ + + + + + + + + + +

Purpose +

Reports or sets whether the machine can export AFS to clients of other file +systems +

Synopsis +

fs exportafs -type <exporter name>  
+        [-start <start/stop translator (on | off)>] 
+        [-convert <convert from afs to unix mode (on | off)>] 
+        [-uidcheck <run on strict 'uid check' mode (on | off)>] 
+        [-submounts <allow nfs mounts to subdirs of /afs/.. (on | off)>]
+        [-help]
+   
+fs exp -t <exporter name>  
+       [-st <start/stop translator (on | off)>]
+       [-c <convert from afs to unix mode (on | off)>]
+       [-u <run on strict 'uid check' mode (on | off)>]
+       [-su <allow nfs mounts to subdirs of /afs/.. (on | off)>]  
+       [-help]
+

Description +

The fs exportafs command sets (if the -start argument +is provided) or reports (if it is omitted) whether the machine can reexport +the AFS filespace to clients of a non-AFS file system. To control +certain features of the translation protocol, use the following +arguments: +

To control whether the UNIX group and other mode +bits on an AFS file or directory are set to match the owner mode +bits when it is exported to the non-AFS file system, use the +-convert argument. +
To control whether tokens can be placed in a credential structure +identified by a UID that differs from the local UID of the entity that is +placing the tokens in the structure, use the -uidcheck +argument. The most common use is to control whether issuers of the +knfs command can specify a value for its -id argument +that does not match their local UID on the NFS/AFS translator machine. +
To control whether users can create mounts in the non-AFS filespace to an +AFS directory other than /afs, use the -submounts +argument. +

Options +

-type +

Names the alternate file system to which to reexport the AFS +filespace. The only acceptable value is nfs, in lowercase +letters only. +

-start +

Enables the local machine to reexport the AFS filespace if the value is +on, or disables it if the value is off. Omit this +argument to report the current setting for all of the configurable +parameters. +

-convert +

Controls the setting of the UNIX group and other +mode bits on AFS files and directories exported to the non-AFS file +system. If the value is on, they are set to match the +owner mode bits. If the value is off, the bits +are not changed. If this argument is omitted, the default value is +on. +

-uidcheck +

Controls whether tokens can be placed in a credential structure identified +by a UID that differs from the local UID of the entity that is placing the +tokens in the structure. +

If the value is on, the UID that identifies the credential +structure must match the local UID. +
With respect to the knfs command, this value means that the +value of -id argument must match the issuer's local UID on the +translator machine. In practice, this setting makes it pointless to +include the -id argument to the knfs command, because +the only acceptable value (the issuer's local UID) is already used when +the -id argument is omitted. +
Enabling UID checking also makes it impossible to issue the klog +and pagsh commands on a client machine of the non-AFS file system +even though it is a system type supported by AFS. For an explanation, +see the reference page for the klog command. +
If the value is off (the default), tokens can be assigned to a +local UID in the non-AFS file system that does not match the local UID of the +entity assigning the tokens. +
With respect to the knfs command, it means that the issuer can +use the -id argument to assign tokens to a local UID on the NFS +client machine that does not match his or her local UID on the translator +machine. (An example is assigning tokens to the MFS client +machine's local superuser root.) This setting allows +more than one issuer of the knfs command to make tokens available +to the same user on the NFS client machine. Each time a different user +issues the knfs command with the same value for the -id +argument, that user's tokens overwrite the existing ones. This can +result in unpredictable access for the user on the NFS client machine. +

-submounts +

Controls whether a user of the non-AFS filesystem can mount any directory +in the AFS filespace other than the top-level /afs +directory. If the value is on, such submounts are +allowed. If the value is off, only mounts of the /afs +directory are allowed. If this argument is omitted, the default value +is off. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

If the machine is not even configured as a server of the non-AFS file +system, the following message appears: +

   Sorry, the file_system-exporter type is currently not supported on
+   this AFS client
+   
+

If the machine is configured as a server of the non-AFS file system but is +not currently enabled to reexport AFS to it (because the -start +argument to this command is not set to on), the message is as +follows: +

   'file_system' translator is disabled
+   
+

If the machine is enabled to reexport AFS, the following message precedes +messages that report the settings of the other parameters. +

   'file_system' translator is enabled with the following options:
+   
+

The following messages indicate that the -convert argument is +set to on or off respectively: +

   Running in convert owner mode bits to world/other mode
+   Running in strict unix mode
+   
+

The following messages indicate that the -uidcheck argument is +set to on or off respectively: +

   Running in strict 'passwd sync' mode
+   Running in no 'passwd sync' mode
+    
+

The following messages indicate that the -submounts argument is +set to on or off respectively: +

   Allow mounts of /afs/.. subdirs
+   Only mounts to /afs allowed
+   
+

Examples +

The following example shows that the local machine can export AFS to NFS +client machines. +

   % fs exportafs nfs
+   'nfs' translator is enabled with the following options:
+        Running in convert owner mode bits to world/other mode
+        Running in no 'passwd sync' mode
+        Only mounts to /afs allowed
+   
+

The following example enables the machine as an NFS server and converts the +UNIX group and other mode bits on exported AFS +directories and files to match the UNIX owner mode bits. +

   % fs exportafs -type nfs -start on -convert on
+   
+

The following example disables the machine from reexporting AFS to NFS +client machines: +

   % fs exportafs -type nfs -start off
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

klog +

knfs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf140.htm b/doc/html/AdminReference/auarf140.htm new file mode 100644 index 0000000..23c751e --- /dev/null +++ b/doc/html/AdminReference/auarf140.htm @@ -0,0 +1,84 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs flush

+ + + + + + + +

Purpose +

Forces the Cache Manager to discard a cached file or directory +

Synopsis +

fs flush [-path <dir/file path>⁺]  [-help]
+   
+fs flush [-p <dir/file path>⁺]  [-h]
+

Description +

The fs flush command removes from the cache all data and status +information associated with each specified file or directory. The next +time an application requests data from the flushed directory or file, the +Cache Manager fetches the most current version from a File Server, along with +a new callback (if necessary) and associated status information. This +command has no effect on two types of data: +

Data in application program buffers +
Data that has been changed locally and written to the cache but not yet +written to the copy on the file server machine +

To flush all data in the cache that was fetched from the same volume as a +specified file or directory, use the fs flushvolume command. +To flush a corrupted mount point, use the fs flushmount +command. +

Options +

-path +: Names each file or directory to flush from the cache. If it is a +directory, only the directory element itself is flushed, not data cached from +files or subdirectories that reside in it. Partial pathnames are +interpreted relative to the current working directory, which is also the +default value if this argument is omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command flushes from the cache the file +projectnotes in the current working directory and all data from the +subdirectory plans: +

   % fs flush -path projectnotes ./plans/*
+   
+

Privilege Required +

Related Information +

fs flushmount +

fs flushvolume +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf141.htm b/doc/html/AdminReference/auarf141.htm new file mode 100644 index 0000000..db53410 --- /dev/null +++ b/doc/html/AdminReference/auarf141.htm @@ -0,0 +1,80 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs flushmount

+ + + + + + +

Purpose +

Forces the Cache Manager to discard a mount point +

Synopsis +

fs flushmount [-path <dir/file path>⁺]  [-help]
+   
+fs flushm [-p <dir/file path>⁺]  [-h]
+

Description +

The fs flushmount command removes from the cache all information +associated with each mount point named by the -path +argument. The next time an application accesses the mount point, the +Cache Manager fetches the most current version of it from the File +Server. Data cached from the associated volume is not affected. +

The command's intended use is to discard information about mount +points that has become corrupted in the cache. (The Cache Manager +periodically refreshes cached mount points, but the only other way to discard +them immediately is to reinitialize the Cache Manager by rebooting the +machine.) Symptoms of a corrupted mount point included garbled output +from the fs lsmount command, and failed attempts to change +directory to or list the contents of a mount point. +

To flush cached data rather than a mount point, use the fs flush +or fs flushvolume command. +

Options +

-path +: Names each mount point to flush from the cache. Partial pathnames +are interpreted relative to the current working directory, which is also the +default value if this argument is omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command flushes from the cache the mount point for user +pat's home directory: +

   % fs flushm /afs/abc.com/usr/pat
+   
+

Privilege Required +

Related Information +

fs flush +

fs flushvolume +

fs lsmount +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf142.htm b/doc/html/AdminReference/auarf142.htm new file mode 100644 index 0000000..6722c38 --- /dev/null +++ b/doc/html/AdminReference/auarf142.htm @@ -0,0 +1,81 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs flushvolume

+ + + + + + +

Purpose +

Forces the Cache Manager to discard all cached data from the volume +containing a file or directory +

Synopsis +

fs flushvolume [-path <dir/file path>⁺]  [-help]
+   
+fs flushv [-p <dir/file path>⁺]  [-h]
+

Description +

The fs flushvolume command removes from the cache all data that +was fetched from the same volume as each specified directory or file. +It does not discard cached status information. The next time an +application requests data from a flushed directory or file, the Cache Manager +fetches the most current version from a File Server, along with a new callback +(if necessary) and associated status information. This command has no +effect on two types of data: +

Data in application program buffers +
Data that has been changed locally and written to the cache but not yet +written to the copy on the file server machine +

To discard the data and status information associated with individual files +and directories, use the fs flush command. To flush a +corrupted mount point, use the fs flushmount command. +

Options +

-path +: Names a file or directory from each volume for which to discard all cached +data. Partial pathnames are interpreted relative to the current working +directory, which is also the default value if this argument is omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command flushes from the cache all data fetched from the +volume that contains the current working directory: +

   % fs flushvolume 
+   
+

Privilege Required +

Related Information +

fs flush +

fs flushmount +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf143.htm b/doc/html/AdminReference/auarf143.htm new file mode 100644 index 0000000..5294990 --- /dev/null +++ b/doc/html/AdminReference/auarf143.htm @@ -0,0 +1,75 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs getcacheparms

+ + + + + + + + +

Purpose +

Displays the current size of the cache and the amount being used +

Synopsis +

fs getcacheparms [-help]
+   
+fs getca [-h]
+

Description +

The fs getcacheparms command displays the current size of the +cache (which can be in memory or on disk), and the amount currently in +use. +

The reported statistics are from kernel memory, so the reported size can +differ from the setting specified in the /usr/vice/etc/cacheinfo +file on a machine using a disk cache, if the fs setcachesize +command has been used to alter cache size. +

Options +

-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output reports +

   AFS using amount used of the cache's available size 1K byte blocks.
+   
+

where amount used is the number of kilobyte blocks currently used +to cache data and status information, and size is the total current +cache size. +

Examples +

The following example shows the output on a machine with a 25000 kilobyte +cache. +

   % fs getcacheparms
+   AFS using 22876 of the cache's available 25000 1K byte blocks.
+   
+

Privilege Required +

None +

Related Information +

fs setcachesize +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf144.htm b/doc/html/AdminReference/auarf144.htm new file mode 100644 index 0000000..0890f16 --- /dev/null +++ b/doc/html/AdminReference/auarf144.htm @@ -0,0 +1,76 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs getcellstatus

+ + + + + + +

Purpose +

Reports whether the machine can run setuid programs from a specified cell +

Synopsis +

fs getcellstatus -cell <cell name>⁺  [-help]
+   
+fs getce -c <cell name>⁺  [-h]
+

Description +

The fs getcellstatus command reports whether the Cache Manager +allows programs fetched from each specified cell to run with setuid +permission. To set a cell's setuid status, use the fs +setcell command; its reference page fully describes how AFS treats +setuid programs. +

Options +

-cell +: Names each cell for which to report setuid status. Provide the +fully qualified domain name, or a shortened form that disambiguates it from +the other cells listed in the local /usr/vice/etc/CellServDB +file. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output reports one of the following two values as appropriate: +

   Cell cell status: setuid allowed
+   Cell cell status: no setuid allowed
+   
+

Examples +

The following example indicates that programs from the cell +abc.com are not allowed to run with setuid +permission. +

   % fs getcellstatus abc.com
+   Cell abc.com status: no setuid allowed
+   
+

Privilege Required +

None +

Related Information +

fs setcell +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf145.htm b/doc/html/AdminReference/auarf145.htm new file mode 100644 index 0000000..9845a1d --- /dev/null +++ b/doc/html/AdminReference/auarf145.htm @@ -0,0 +1,106 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs getclientaddrs

+ + + + + +

Purpose +

Displays the client interfaces to register with the File Server +

Synopsis +

fs getclientaddrs [-help]
+      
+fs gc [-h]
+     
+fs getcl [-h]
+

Description +

The fs getclientaddrs command displays the IP addresses of the +interfaces that the local Cache Manager registers with a File Server when +first establishing a connection to it. +

If an RPC to that interface fails, the File Server simultaneously sends +RPCs to all of the other interfaces in the list, to learn which of them are +still available. Whichever interface replies first is the one to which +the File Server then sends pings and RPCs to break callbacks. +

The fs setclientaddrs reference page explains how the Cache +Manager constructs the list automatically in kernel memory as it initializes, +and how to use that command to alter the kernel list after +initialization. +

Cautions +

The File Server uses the list of interfaces displayed by this command only +when selecting an alternative interface after a failed attempt to break a +callback or ping the Cache Manager. When responding to the Cache +Manager's request for file system data, the File Server replies to the +interface which the Cache Manager used when sending the request. If the +File Server's reply to a data request fails, the file server +machine's network routing configuration determines which alternate +network routes to the client machine are available for resending the +reply. +

The displayed list applies to all File Servers to which the Cache Manager +connects in the future. It is not practical to register different sets +of addresses with different File Servers, because it requires using the +fs setclientaddrs command to change the list and then rebooting +each relevant File Server immediately. +

The displayed list is not necessarily governing the behavior of a given +File Server, if an administrator has issued the fs setclientaddrs +command since the Cache Manager first contacted that File Server. It +determines only which addresses the Cache Manager registers when connecting to +File Servers in the future. +

The list of interfaces does not influence the Cache Manager's choice +of interface when establishing a connection to a File Server. +

Options +

-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output displays the IP address of each interface that the Cache Manager +is currently registering with File Server processes that it contacts, with one +address per line. The File Server initially uses the first address for +breaking callbacks and pinging the Cache Manager, but the ordering of the +other interfaces is not meaningful. +

Examples +

The following example displays the two interfaces that the Cache Manager is +registering with File Servers. +

   % fs getclientaddrs
+   192.12.105.68
+   192.12.108.84
+   
+

Privilege Required +

None +

Related Information +

fs setclientaddrs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf146.htm b/doc/html/AdminReference/auarf146.htm new file mode 100644 index 0000000..36eeb14 --- /dev/null +++ b/doc/html/AdminReference/auarf146.htm @@ -0,0 +1,173 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs getserverprefs

+ + + + + + + +

Purpose +

Displays the Cache Manager's preference ranks for file server or VL +Server machines +

Synopsis +

fs getserverprefs [-file <output to named file>]  
+                  [-numeric]  [-vlservers]  [-help]
+     
+fs gets [-f <output to named file>]  [-n]  [-v]  [-h]
+    
+fs gp [-f <output to named file>]  [-n]  [-v]  [-h]
+

Description +

The fs getserverprefs command displays preference ranks for file +server machine interfaces (file server machines run the fs process) +or, if the -vlserver flag is provided, for Volume Location (VL) +Server machines (which run the vlserver process). For file +server machines, the Cache Manager tracks up to 15 interfaces per machine and +assigns a separate rank to each interface. The ranks indicate the order +in which the local Cache Manager attempts to contact the interfaces of +machines that are housing a volume when it needs to fetch data from the +volume. For VL Server machines, the ranks indicate the order in which +the Cache Manager attempts to contact a cell's VL Servers when requesting +VLDB information. For both types of rank, lower integer values are more +preferred. +

The Cache Manager stores ranks in kernel memory. Once set, a rank +persists until the machine reboots, or until the fs setserverprefs +command is used to change it. The reference page for the fs +setserverprefs command explains how the Cache Manager sets default +ranks, and how to use that command to change the default values. +

Default VL Server ranks range from 10,000 to 10,126, and the Cache Manager +assigns them to every machine listed in its copy of the +/usr/vice/etc/CellServDB file. When the Cache Manager needs +to fetch VLDB information from a cell, it compares the ranks for the VL Server +machines belonging to that cell, and attempts to contact the VL Server with +the lowest integer rank. If the Cache Manager cannot reach the VL +Server (because of server process, machine or network outage), it tries to +contact the VL Server with the next lowest integer rank, and so on. If +all of a cell's VL Server machines are unavailable, the Cache Manager +cannot fetch data from the cell. +

Default file server ranks range from 5,000 to 40,000, excluding the range +used for VL Servers (10,000 to 10,126); the maximum possible rank is +65,534. When the Cache Manager needs to fetch data from a volume, it +compares the ranks for the interfaces of machines that house the volume, and +attempts to contact the interface that has the lowest integer rank. If +it cannot reach the fileserver process via that interface (because +of server process, machine or network outage), it tries to contact the +interface with the next lowest integer rank, and so on. If it cannot +reach any of the interfaces for machines that house the volume, it cannot +fetch data from the volume. +

For both file server machines and VL Server machines, it is possible for a +machine or interface in a foreign cell to have the same rank as a machine or +interface in the local cell. This does not present a problem, because +the Cache Manager only ever compares ranks for machines belonging to one cell +at a time. +

Options +

-file +: Specifies the full pathname of a file to which to write the preference +ranks. If the specified file already exists, the command overwrites its +contents. If the pathname is invalid, the command fails. If this +argument is not provided, the preference ranks appear on the standard output +stream. +
-numeric +: Displays the IP addresses of file server machine interfaces or VL Server +machines, rather than their hostnames. If this argument is not +provided, the fs command interpreter has the IP addresses +translated to hostnames such as fs1.abc.com. +
-vlservers +: Displays preference ranks for VL Server machines rather than file server +machine interfaces. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output consists of a separate line for each file server machine +interface or VL Server machine, pairing the machine's hostname or IP +address with its rank. The Cache Manager stores IP addresses in its +kernel list of ranks, but the command by default identifies interfaces by +hostname, by calling a translation routine that refers to either the +cell's name service (such as the Domain Name Server) or the local host +table. If an IP address appears in the output, it is because the +translation attempt failed. To bypass the translation step and display +IP addresses rather than hostnames, include the -numeric +flag. This can significantly speed the production of output. +

By default, the command writes to the standard output stream. Use +the -file argument to write the output to a file instead. +

Examples +

The following example displays the local Cache Manager's preference +ranks for file server machines. The local machine belongs to the AFS +cell named abc.com, and in this example the ranks of file +server machines in its local cell are lower than the ranks of file server +machines from the foreign cell, def.com. It is not +possible to translate the IP addresses of two machines on the 138.255 +network. +

   % fs getserverprefs
+   fs2.abc.com           20007
+   fs3.abc.com           30002
+   fs1.abc.com           20011
+   fs4.abc.com           30010
+   server1.def.com       40002
+   138.255.33.34         40000
+   server6.def.com       40012
+   138.255.33.37         40005
+   
+

The following example shows hows the output displays IP addresses when the +-numeric flag is included, and illustrates how network proximity +determines default ranks (as described on the fs setserverprefs +reference page). The local machine has IP address +192.12.107.210, and the two file server machines on its +subnetwork have ranks of 20,007 and 20,011. The two file server +machines on a different subnetwork of the local machine's network have +higher ranks, 30,002 and 30,010, whereas the ranks of the remaining machines +range from 40,000 to 40,012 because they are in a completely different +network. +

   % fs getserverprefs -numeric
+   192.12.107.214          20007
+   192.12.105.99           30002
+   192.12.107.212          20011
+   192.12.105.100          30010
+   138.255.33.41           40002
+   138.255.33.34           40000
+   138.255.33.36           40012
+   138.255.33.37           40005
+    
+

The example shows how the -vlservers flag displays preference +ranks for VL Server machines: +

   % fs getserverprefs -vlservers
+   fs2.abc.com            10052
+   fs3.abc.com            10113
+   fs1.abc.com            10005
+    
+

Privilege Required +

None +

Related Information +

fs setserverprefs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf147.htm b/doc/html/AdminReference/auarf147.htm new file mode 100644 index 0000000..5eb6e6e --- /dev/null +++ b/doc/html/AdminReference/auarf147.htm @@ -0,0 +1,85 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs help

+ + + +

Purpose +

Displays the syntax of specified fs commands or lists functional +descriptions of all fs commands +

Synopsis +

fs help [-topic <help string>⁺]  [-help]
+   
+fs h [-t <help string>⁺]  [-h]
+

Description +

The fs help command displays the complete online help entry +(short description and syntax statement) for each command operation code +specified by the -topic argument. If the -topic +argument is omitted, the output includes the first line (name and short +description) of the online help entry for every fs command. +

To display every fs command whose name or short description +includes a specified keyword, use the fs apropos command. +

Options +

-topic +: Indicates each command for which to display the complete online help +entry. Omit the fs part of the command name, providing only +the operation code (for example, specify setacl, not fs +setacl). If this argument is omitted, the output briefly +describes every fs command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each fs command consists of the +following two or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following command displays the 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] [-help]
+   
+

Privilege Required +

None +

Related Information +

fs +

fs apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf148.htm b/doc/html/AdminReference/auarf148.htm new file mode 100644 index 0000000..0e71960 --- /dev/null +++ b/doc/html/AdminReference/auarf148.htm @@ -0,0 +1,175 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs listacl

+ + + + + + +

Purpose +

Displays ACLs +

Synopsis +

fs listacl [-path <dir/file path>⁺]  [-id]  [-if]  [-help]
+   
+fs la [-p <dir/file path>⁺]  [-id]  [-if]  [-h] 
+   
+fs lista [-p <dir/file path>⁺]  [-id]  [-if]  [-h] 
+

Description +

The fs listacl command displays the access control list (ACL) +associated with each specified file, directory, or symbolic link. The +specified element can reside in the DFS filespace if the issuer is using the +AFS/DFS Migration Toolkit Protocol Translator to access DFS data (and DFS does +implement per-file ACLs). To display the ACL of the current working +directory, omit the -path argument. +

To alter an ACL, use the fs setacl command. To copy an +ACL from one directory to another, use the fs copyacl +command. To remove obsolete entries from an ACL, use the fs +cleanacl command. +

Cautions +

Placing a user or group on the Negative rights section of the +ACL does not guarantee denial of permissions, if the Normal rights +section grants the permissions to members of the +system:anyuser group. In that case, the user needs +only to issue the unlog command to obtain the permissions granted +to the system:anyuser group. +

Options +

-path +: Names each directory or file for which to display the ACL. For AFS +files, the output displays the ACL from the file's parent directory; +DFS files do have their own ACL. Incomplete pathnames are interpreted +relative to the current working directory, which is also the default value if +this argument is omitted. +
-id +: Displays the Initial Container ACL of each DFS directory. This +argument is supported only on DFS directories accessed via the AFS/DFS +Migration Toolkit Protocol Translator. +
-if +: Displays the Initial Object ACL of each DFS directory. This +argument is supported only on DFS directories accessed via the AFS/DFS +Migration Toolkit Protocol Translator. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The first line of the output for each file, directory, or symbolic link +reads as follows: +

   Access list for directory is
+   
+

If the issuer used shorthand notation in the pathname, such as the period +(.) to represent the current current directory, that +notation sometimes appears instead of the full pathname of the +directory. +

Next, the Normal rights header precedes a list of users and +groups who are granted the indicated permissions, with one pairing of user or +group and permissions on each line. If negative permissions have been +assigned to any user or group, those entries follow a Negative +rights header. The format of negative entries is the same as +those on the Normal rights section of the ACL, but the user or +group is denied rather than granted the indicated permissions. +

AFS does not implement per-file ACLs, so for a file the command displays +the ACL on its directory. The output for a symbolic link displays the +ACL that applies to its target file or directory, rather than the ACL on the +directory that houses the symbolic link. +

The permissions for AFS enable the possessor to perform the indicated +action: +

a +: (administer): change the entries on the ACL +
d +: (delete): remove files and subdirectories from the +directory or move them to other directories +
i +: (insert): add files or subdirectories to the directory by +copying, moving or creating +
k +: (lock): set read locks or write locks on the files in the +directory +
l +: (lookup): list the files and subdirectories in the +directory, stat the directory itself, and issue the fs listacl +command to examine the directory's ACL +
r +: (read): read the contents of files in the directory; +issue the ls -l command to stat the elements in the directory +
w +: (write): modify the contents of files in the directory, +and issue the UNIX chmod command to change their mode bits +
A, B, C, D, E, +F, G, H: +: Have no default meaning to the AFS server processes, but are made +available for applications to use in controlling access to the +directory's contents in additional ways. The letters must be +uppercase. +

For DFS files and directories, the permissions are similar, except that the +DFS x (execute) permission replaces the AFS l +(lookup) permission, DFS c (control) replaces +AFS a (administer), and there is no DFS equivalent to +the AFS k (lock) permission. The meanings of the +various permissions also differ slightly, and DFS does not implement negative +permissions. For a complete description of DFS permissions, see the DFS +documentation and the IBM AFS/DFS Migration Toolkit Administration Guide +and Reference. +

Examples +

The following command displays the ACL on the home directory of the user +pat (the current working directory), and on its private +subdirectory. +

   % fs listacl -path . private
+   Access list for . is
+   Normal rights:
+      system:authuser rl
+      pat rlidwka
+      pat:friends rlid
+   Negative rights:
+      smith rlidwka
+   Access list for private is
+   Normal rights:
+      pat rlidwka
+   
+

Privilege Required +

If the -path argument names an AFS directory, the issuer must +have the l (lookup) permission on its ACL and the ACL +for every directory that precedes it in the pathname. +

If the -path argument names an AFS file, the issuer must have +the l (lookup) and r (read) +permissions on the ACL of the file's directory, and the l +permission on the ACL of each directory that precedes it in the +pathname. +

If the -path argument names a DFS directory or file, the issuer +must have the x (execute) permission on its ACL and on +the ACL of each directory that precedes it in the pathname. +

Related Information +

fs cleanacl +

fs copyacl +

fs setacl +

IBM AFS/DFS Migration Toolkit Administration Guide and Reference +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf149.htm b/doc/html/AdminReference/auarf149.htm new file mode 100644 index 0000000..7aee8b6 --- /dev/null +++ b/doc/html/AdminReference/auarf149.htm @@ -0,0 +1,89 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs listcells

+ + + + + + + + + +

Purpose +

Displays the database server machines in each cell known to the Cache +Manager +

Synopsis +

fs listcells [-numeric]  [-help]
+   
+fs listc [-n]  [-h]
+

Description +

The fs listcells command formats and displays the list of the +database server machines that the Cache Manager stores in kernel memory for +its home cell and foreign cells. +

At each reboot of the client machine, the Cache Manager copies the contents +of /usr/vice/etc/CellServDB into kernel memory. To modify +the list between reboots, use the fs newcell command. +

Options +

-numeric +: Displays each database server machine's IP address rather than +hostname. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output includes a line for each cell included in the Cache +Manager's kernel memory list, in the following format: +

   Cell cell on hosts database server machines
+   
+

The Cache Manager stores IP addresses, but by default has them translated +to hostnames before reporting them, by passing them to the cell's name +service (such as the Domain Name Service or a local host table). The +name service sometimes returns hostnames in uppercase letters, or an IP +address if it cannot resolve a name. +

Using the -numeric flag bypasses the translation to hostnames, +which can result in significantly faster production of output. The +output includes IP addresses only. +

Examples +

The following example shows output for several cells as illustrations of +the different formats for machine names: +

   % fs listcells
+   Cell abc.com on hosts fs1.abc.com fs2.abc.com fs3.abc.com
+   Cell stateu.edu on hosts DB1.FS.STATEU.EDU 
+      DB2.FS.STATEU.EDU DB3.FS.STATEU.EDU
+   Cell def.gov on hosts 138.255.0.2 sv3.def.gov
+    
+

Privilege Required +

None +

Related Information +

fs newcell +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf150.htm b/doc/html/AdminReference/auarf150.htm new file mode 100644 index 0000000..192094c --- /dev/null +++ b/doc/html/AdminReference/auarf150.htm @@ -0,0 +1,113 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs listquota

+ + + + + + + + + + + + + + + +

Purpose +

Displays quota information for the volume containing a file or +directory. +

Synopsis +

fs listquota [-path <dir/file path>⁺]  [-help]  
+   
+fs listq [-p <dir/file path>⁺]  [-h]
+      
+fs lq [-p <dir/file path>⁺]  [-h]
+

Description +

The fs listquota command displays information about the volume +containing each specified directory or file (its name, quota, and amount of +disk space used), along with an indicator of the percentage of space used on +the host partition. +

To display more information about the host partition, use the fs +examine command. +

To set volume quota, use the fs setquota or fs setvol +command. +

Options +

-path +: Names a file or directory that resides in the volume about which to +produce output. Partial pathnames are interpreted relative to the +current working directory, which is also the default value if this argument is +omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output displays information about the volume that houses each specified +directory or file, in a tabular format that uses the following headers: +

Volume Name +: The name of the volume. +
Quota +: The volume's quota in kilobytes, or the string no limit to +indicate an unlimited quota. +
Used +: The number of kilobytes of quota used. +
% Used +: The percentage of the volume's quota that is used (the +Used statistic divided by the Quota statistic, times +100). +
Partition +: The percentage of space used on the partition that houses the +volume. Although not directly related to how much of the user's +quota is used, it is reported because a full partition can cause writing of +data back to the volume to fail even when the volume has not reached its +quota. +

Examples +

The following example shows the output for the volume +user.smith: +

   % fs listquota -path /afs/abc.com/usr/smith
+   Volume Name     Quota    Used    % Used   Partition 
+   user.smith      15000    5071       34%         86%   
+    
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf151.htm b/doc/html/AdminReference/auarf151.htm new file mode 100644 index 0000000..e082cfd --- /dev/null +++ b/doc/html/AdminReference/auarf151.htm @@ -0,0 +1,120 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs lsmount

+ + + + + +

Purpose +

Reports the volume for which a directory is the mount point. +

Synopsis +

fs lsmount -dir <directory>⁺  [-help]
+   
+fs ls -d <directory>⁺  [-h] 
+

Description +

The fs lsmount command reports the volume for which each +specified directory is a mount point, or indicates with an error message that +a directory is not a mount point or is not in AFS. +

To create a mount point, use the fs mkmount command. To +remove one, use the fs rmmount command. +

Options +

-dir +: Names the directory that serves as a mount point for a volume. The +last element in the pathname provided must be an actual name, not a shorthand +notation such as one or two periods (. or +..). +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

If the specified directory is a mount point, the output is of the following +form: +

   'directory' is a mount point for volume 'volume name'
+   
+

where +

A number sign (#) precedes the volume name string for +a regular mount point. +
A percent sign (%) precedes the volume name string for +a read/write mount point. +
A cell name and colon (:) follow the number or percent +sign and precede the volume name string for a cellular mount +point. +

The fs mkmount reference page explains how the Cache Manager +interprets each of the three types of mount points. +

If the directory is a symbolic link to a mount point, the output is of the +form: +

   'directory' is a symbolic link, leading to a mount point for volume 'volume name'
+   
+

If the directory is not a mount point or is not in AFS, the output +reads: +

   'directory' is not a mount point.
+   
+

If the output is garbled, it is possible that the mount point has become +corrupted in the local AFS client cache. Use the fs +flushmount command to discard it, which forces the Cache Manager to +refetch the mount point. +

Examples +

The following example shows the mount point for the home directory of user +smith: +

   % fs lsmount /afs/abc.com/usr/smith
+   '/afs/abc.com/usr/smith' is a mount point for volume '#user.smith'
+   
+

The following example shows both the regular and read/write mount points +for the ABC Corporation cell's root.cell volume. +

   % fs lsmount /afs/abc.com
+   '/afs/abc.com' is a mount point for volume '#root.cell'
+   
+   % fs lsmount /afs/.abc.com
+   '/afs/.abc.com' is a mount point for volume '%root.cell'
+   
+

The following example shows a cellular mount point: the State +University cell's root.cell volume as mounted in the +ABC Corporation cell's tree. +

   % fs lsmount /afs/stateu.edu
+   '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
+   
+

Privilege Required +

The issuer must have the l (lookup) permission on the +ACL of the root directory of the volume that houses the file or directory +named by the -dir argument, and on the ACL of each directory that +precedes it in the pathname. +

Related Information +

fs flushmount +

fs rmmount +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf152.htm b/doc/html/AdminReference/auarf152.htm new file mode 100644 index 0000000..f49714c --- /dev/null +++ b/doc/html/AdminReference/auarf152.htm @@ -0,0 +1,82 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs messages

+ + + + +

Purpose +

Sets whether the Cache Manager writes log messages +

Synopsis +

fs messages [-show <[user|console|all|none]>]  [-help]
+    
+fs me [-s <[user|console|all|none]>]  [-h]
+

Description +

The fs messages command controls whether the Cache Manager +displays status and warning messages on user screens, the client machine +console, on both, or on neither. +

There are two types of Cache Manager messages: +

User messages provide user-level status and warning information, and the +Cache Manager directs them to user screens. +
Console messages provide system-level status and warning information, and +the Cache Manager directs them to the client machine's designated +console. +

Disabling messaging completely is not recommended, because the messages +provide useful status and warning information. +

Options +

-show +

Specifies the types of messages to display. Choose one of the +following values: +

user +: Send user messages to user screens +
console +: Send console messages to the console +
all +: Send user messages to user screens and console messages to the console +(the default if the -show argument is omitted) +
none +: Do not send any messages to user screens or the console +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command instructs the Cache Manager to display both types of +messages: +

   % fs messages -show all
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

afsd +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf153.htm b/doc/html/AdminReference/auarf153.htm new file mode 100644 index 0000000..6091f1f --- /dev/null +++ b/doc/html/AdminReference/auarf153.htm @@ -0,0 +1,240 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs mkmount

+ + + + + +

Purpose +

Creates a mount point for a volume +

Synopsis +

fs mkmount -dir <directory>  -vol <volume name>  [-cell <cell name>]
+           [-rw]  [-fast]  [-help]
+   
+fs mk -d <directory>  -v <volume name>  [-c <cell name>]  [-r]  [-f]  [-h]
+

Description +

The fs mkmount command creates a mount point for the volume +named by the -vol argument at the location in the AFS file space +specified by the -dir argument. The mount point looks like a +standard directory element, and serves as the volume's root directory, +but is actually a special file system object that refers to an AFS +volume. When the Cache Manager first encounters a given mount point +during pathname traversal, it contacts the VL Server to learn which file +server machines house the indicated volume, then fetches a copy of the +volume's root directory from the appropriate file server machine. +

It is possible, although not recommended, to create more than one mount +point to a volume. The Cache Manager can become confused if a volume is +mounted in two places along the same path through the filespace. +

The Cache Manager observes three basic rules as it traverses the AFS +filespace and encounters mount points: +

Rule 1: Access Backup and Read-only Volumes When +Specified +
When the Cache Manager encounters a mount point that specifies a volume +with either a .readonly or a .backup +extension, it accesses that type of volume only. If a mount point does +not have either a .backup or .readonly +extension, the Cache Manager uses Rules 2 and 3. +
For example, the Cache Manager never accesses the read/write version of a +volume if the mount point names the backup version. If the specified +version is inaccessible, the Cache Manager reports an error. +
Rule 2: Follow the Read-only Path When Possible +
If a mount point resides in a read-only volume and the volume that it +references is replicated, the Cache Manager attempts to access a read-only +copy of the volume; if the referenced volume is not replicated, the Cache +Manager accesses the read/write copy. The Cache Manager is thus said to +prefer a read-only path through the filespace, accessing read-only +volumes when they are available. +
The Cache Manager starts on the read-only path in the first place because +it always accesses a read-only copy of the root.afs volume +if it exists; the volume is mounted at the root of a cell's AFS +filespace (named /afs by convention). That is, if the +root.afs volume is replicated, the Cache Manager attempts to +access a read-only copy of it rather than the read/write copy. This +rule then keeps the Cache Manager on a read-only path as long as each +successive volume is replicated. The implication is that both the +root.afs and root.cell volumes must be +replicated for the Cache Manager to access replicated volumes mounted below +them in the AFS filespace. The volumes are conventionally mounted at +the /afs and /afs/cellname directories, +respectively. +
Rule 3: Once on a Read/write Path, Stay There +
If a mount point resides in a read/write volume and the volume name does +not have a .readonly or a .backup +extension, the Cache Manager attempts to access only the a read/write version +of the volume. The access attempt fails with an error if the read/write +version is inaccessible, even if a read-only version is accessible. In +this situation the Cache Manager is said to be on a read/write path +and cannot switch back to the read-only path unless mount point explicitly +names a volume with a .readonly extension. (Cellular +mount points are an important exception to this rule, as explained in the +following discussion. +

There are three types of mount points, each appropriate for a different +purpose because of the manner in which the Cache Manager interprets +them. +

When the Cache Manager crosses a regular mount point, it obeys +all three of the mount point traversal rules previously described. To +create a regular mount point, include only the required -dir and +-vol arguments to the fs mkmount command. + + +

Note:

A regular mount point does not force the Cache Manager always to access +read-only volumes (it is explicitly not a "read-only mount point"). If +a volume is not replicated, the third traversal rule means that the Cache +Manager still accesses the read/write volume when that is the only type +available. However, if the Cache Manager is to access the read-only +version of a replicated volume named by a regular mount point, all volumes +that are mounted above it in the pathname must also be replicated. +

When the Cache Manager crosses a read/write mount point, it +attempts to access only the volume version named in the mount point. If +the volume name is the base (read/write) form, without a +.readonly or .backup extension, the Cache +Manager accesses the read/write version of the volume, even if it is +replicated. In other words, the Cache Manager disregards the second +mount point traversal rule when crossing a read/write mount point: it +switches to the read/write path through the filespace. + + +
To create a read/write mount point, include the -rw flag on the +fs mkmount command. It is conventional to create only one +read/write mount point in a cell's filespace, using it to mount the +cell's root.cell volume just below the AFS filespace +root (by convention, /afs/.cellname). See +the IBM AFS Quick Beginnings for instructions and the chapter about +volume management in the IBM AFS Administration Guide for further +discussion. +
Creating a read/write mount point for a read-only or backup volume is +acceptable, but unnecessary. The first rule of mount point traversal +already specifies that the Cache Manager accesses them if the volume name in a +regular mount point has a .readonly or +.backup extension. +
When the Cache Manager crosses a cellular mount point, it +accesses the indicated volume in the specified cell, which is normally a +foreign cell. (If the mount point does not name a cell along with the +volume, the Cache Manager accesses the volume in the cell where the mount +point resides.) The Cache Manager disregards the third mount point +traversal rule when crossing a regular cellular mount point: it accesses +a read-only version of the volume if it is replicated, even if the volume that +houses the mount point is read/write. Switching to the read-only path +in this way is designed to avoid imposing undue load on the file server +machines in foreign cells. + + + +
To create a regular cellular mount point, include the -cell +argument on the fs mkmount command. It is conventional to +create cellular mount points only at the second level in a cell's +filespace, using them to mount foreign cells' root.cell +volumes just below the AFS filespace root (by convention, at +/afs/foreign_cellname). The mount point enables +local users to access the foreign cell's filespace, assuming they have +the necessary permissions on the ACL of the volume's root directory and +that there is an entry for the foreign cell in each local client +machine's /usr/vice/etc/CellServDB file. In the output +of the fs lsmount command, the cell name and a colon +(:) appear between the initial number sign and the volume +name in a regular cellular mount point name. +

Options +

-dir +

Names the directory to create as a mount point. The directory must +not already exist. Relative pathnames are interpreted with respect to +the current working directory. +

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. 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 +Description section of this reference page. +

-vol +

Specifies the name or volume ID number of the volume to mount. If +appropriate, add the .readonly or .backup +extension to the name, or specify the appropriate volume ID number. +

-cell +

Names the cell in which the volume resides (creates a cellular mount +point). Provide the fully qualified domain name, or a shortened form +that disambiguates it from the other cells listed in the local +/usr/vice/etc/CellServDB file. +

If this argument is omitted, no cell indicator appears in the mount +point. When the Cache Manager interprets it, it assumes that the volume +named in the mount point resides in the same cell as the volume that houses +the mount point. +

-rw +

Creates a read/write mount point. Omit this flag to create a +regular mount point. +

-fast +

Prevents the Volume Location (VL) Server from checking that the volume has +a VLDB entry and printing a warning message if it does not. Whether or +not this flag is included, the File Server creates the mount point even when +the volume has no VLDB entry. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command creates a regular mount point, mounting the volume +user.smith at +/afs/abc.com/usr/smith: +

   % cd /afs/abc.com/usr
+      
+   % fs mkmount -dir smith -vol user.smith
+   
+

The following commands create a read/write mount point and a regular mount +point for the ABC Corporation cell's root.cell volume +in that cell's file tree. The second command follows the +convention of putting a period at the beginning of the read/write mount +point's name. +

   % fs mkmount -dir /afs/abc.com -vol root.cell
+   
+   % fs mkmount -dir /afs/.abc.com -vol root.cell -rw
+   
+

The following command mounts the State University cell's +root.cell volume in the ABC Corporation cell's file +tree, creating a regular cellular mount point called +/afs/stateu.edu. When a ABC Corporation Cache Manager +encounters this mount point, it crosses into the State University cell on a +read-only path. +

   % fs mkmount -dir /afs/stateu.edu -vol root.cell -c stateu.edu
+   
+

Privilege Required +

The issuer must have the i (insert) and a +(administer) permissions on the ACL of the directory that is to +house the mount point. +

Related Information +

fs lsmount +

fs rmmount +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf154.htm b/doc/html/AdminReference/auarf154.htm new file mode 100644 index 0000000..bc07d0b --- /dev/null +++ b/doc/html/AdminReference/auarf154.htm @@ -0,0 +1,116 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs newcell

+ + + + + + + + +

Purpose +

Changes the kernel-resident list of a cell's database server machines +

Synopsis +

fs newcell -name <cell name> -servers <primary servers>⁺
+           [-linkedcell <linked cell name>]  [-help]
+   
+fs n -n <cell name>  -s <primary servers>⁺  [-l <linked cell name>]  [-h]
+

Description +

The fs newcell command removes the Cache Manager's +kernel-resident list of database server machines for the cell specified by the +-name argument and replaces it with the database server machines +named by the -servers argument. +

Each time the machine reboots, the Cache Manager constructs the kernel list +of cells and database server machines by reading the local +/usr/vice/etc/CellServDB file. This command does not change +the CellServDB file, so any changes made with it persist only until +the next reboot, unless the issuer also edits the file. The output of +the fs listcells command reflects changes made with this command, +because that command consults the kernel-resident list rather than the +CellServDB file. +

This command can introduce a completely new cell into the kernel-resident +list, but cannot make a cell inaccessible (it is not possible to remove a +cell's entry from the kernel-resident list by providing no values for the +-server argument). To make a cell inaccessible, remove its +entry from the CellServDB file and reboot the machine. +

If the -name argument names a DCE cell, then the +-servers argument names DFS Fileset Location (FL) Server +machines. The -linkedcell argument specifies the name of the +AFS cell to link to a DCE cell for the purpose of DFS fileset location. +Refer to the IBM AFS/DFS Migration Toolkit Administration Guide and +Reference for more information on linking AFS clients to DCE cells using +this command or by editing the /usr/vice/etc/CellServDB +file. +

Cautions +

Some commands, such as the klog command, work correctly only +when the information is accurate for a cell in both the CellServDB +file and the kernel-resident list. +

Options +

-name +: Specifies the fully-qualified cell name of the AFS or DCE cell. +
-servers +: Specifies the fully-qualified hostnames of all AFS database server +machines or DFS Fileset Location (FL) Server machines for the cell named by +the -name argument. If FL Server machines are specified, the +local machine must be running the AFS/DFS Migration Toolkit Protocol +Translator. +
-linkedcell +: Specifies the name of the AFS cell to link to a DCE cell for the purpose +of DFS fileset location. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example changes the machine's kernel-resident list of +database server machines for the ABC Corporation cell to include the machines +db1.abc.com and +db2.abc.com: +

   % fs newcell -name abc.com -servers db1.abc.com db2.abc.com
+   
+

The following example links the DCE cell +dce.abc.com to the AFS cell +abc.com. The AFS client contacts the Fileset Location +(FL) servers db1.dce.abc.com and +db2.dce.abc.com for fileset location +information as it interprets a DFS pathname. +

   % fs newcell -name dce.abc.com -servers db1.dce.abc.com db2.dce.abc.com   \
+                -linkedcell abc.com
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fs listcells +

IBM AFS/DFS Migration Toolkit Administration Guide and Reference +

IBM AFS/DFS Migration Toolkit Administration Installation and +Configuration Guide +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf155.htm b/doc/html/AdminReference/auarf155.htm new file mode 100644 index 0000000..e9aa7ae --- /dev/null +++ b/doc/html/AdminReference/auarf155.htm @@ -0,0 +1,90 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs quota

+ + + + + +

Purpose +

Displays the percentage of quota used in the volume containing a directory +or file +

Synopsis +

fs quota [-path <dir/file path>⁺]  [-help]
+    
+fs q [-p <dir/file path>⁺]  [-h]
+

Description +

The fs quota command displays the percent of quota consumed in +the volume that contains each specified directory or file. +

To display more detailed information about the volume and the partition it +resides on, use the fs examine and fs listquota +commands. +

To set volume quota, use the fs setquota or fs setvol +command. +

Options +

-path +: Names each file or directory for which to display the quota consumed in +its parent volume. Partial pathnames are interpreted relative to the +current working directory, which is also the default value if this argument is +omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output reports the percent of volume quota used, in the following +format: +

   percent% of quota used.
+   
+

Examples +

The following command lists the percent quota used of the volume housing +the current working directory: +

   % fs quota
+   17% of quota used.
+   
+

The following command lists the percent quota used of both the volume +housing the current working directory's parent directory and the volume +housing the directory /afs/abc.com/usr/smith: +

   % fs quota -path  ..  /afs/abc.com/usr/smith
+   43% of quota used.
+   92% of quota used.
+   
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf156.htm b/doc/html/AdminReference/auarf156.htm new file mode 100644 index 0000000..55aa8d5 --- /dev/null +++ b/doc/html/AdminReference/auarf156.htm @@ -0,0 +1,75 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs rmmount

+ + + + + + +

Purpose +

Removes a mount point +

Synopsis +

fs rmmount -dir <directory>⁺  [-help]
+      
+fs rm -d <directory>⁺  [-h]
+

Description +

The fs rmmount command removes the mount point named by the +-dir argument from the file system. The corresponding volume +remains on its host partition or partitions, but is inaccessible if there are +no other mount points for it. +

Options +

-dir +

Names the mount point to delete from the file system. The last +element in the pathname must be an actual name, not a shorthand notation such +as "dot" (.) or "dot dot" (. .). +

Specify the read/write path to the directory, to avoid the failure that +results from attempting to delete a mount point from 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 +fs mkmount reference page. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command removes the mount points jones and +terry from the current working directory (the +/afs/abc.com/usr directory). +

   % fs rmmount jones terry
+    
+

Privilege Required +

The issuer must have the d (delete) permission on the +ACL of the directory that houses each mount point. +

Related Information +

fs lsmount +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf157.htm b/doc/html/AdminReference/auarf157.htm new file mode 100644 index 0000000..f5fa9ef --- /dev/null +++ b/doc/html/AdminReference/auarf157.htm @@ -0,0 +1,259 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs setacl

+ + + + + + + + + + + + + +

Purpose +

Sets the ACL for a directory +

Synopsis +

fs setacl -dir <directory>⁺  -acl <access list entries>⁺  
+          [-clear]  [-negative]  [-id]  [-if]  [-help]
+    
+fs sa -d <directory>⁺  -a <access list entries>⁺  
+      [-c]  [-n]  [-id]  [-if]  [-h] 
+      
+fs seta -d <directory>⁺  -a <access list entries>⁺  
+        [-c]  [-n]  [-id]  [-if]  [-h]
+

Description +

The fs setacl command adds the access control list (ACL) entries +specified with the -acl argument to the ACL of each directory named +by the -dir argument. +

If the -dir argument designates a pathname in DFS filespace +(accessed via the AFS/DFS Migration Toolkit Protocol Translator), it can be a +file as well as a directory. The ACL must already include an entry for +mask_obj, however. For more details, refer to the IBM +AFS/DFS Migration Toolkit Administration Guide and Reference. +

Only user and group entries are acceptable values for the -acl +argument. Do not place machine entries (IP addresses) directly on an +ACL; instead, make the machine entry a group member and place the group +on the ACL. +

To completely erase the existing ACL before adding the new entries, provide +the -clear flag. To add the specified entries to the +Negative rights section of the ACL (deny rights to +specified users or groups), provide the -negative flag. +

To display an ACL, use the fs listacl command. To copy an +ACL from one directory to another, use the fs copyacl +command. +

Cautions +

If the ACL already grants certain permissions to a user or group, the +permissions specified with the fs setacl command replace the +existing permissions, rather than being added to them. +

Setting negative permissions is generally unnecessary and not +recommended. Simply omitting a user or group from the Normal +rights section of the ACL is normally adequate to prevent +access. In particular, note that it is futile to deny permissions that +are granted to members of the system:anyuser group on the +same ACL; the user needs only to issue the unlog command to +receive the denied permissions. +

When including the -clear option, be sure to reinstate an entry +for each directory's owner that includes at least the l +(lookup) permission. Without that permission, it is +impossible to resolve the "dot" ( . ) and "dot dot" ( . . +) shorthand from within the directory. (The directory's owner does +implicitly have the a [administer] permission even on a +cleared ACL, but must know to use it to add other permissions.) +

Options +

-dir +

Names each AFS directory, or DFS directory or file, for which the set the +ACL. Partial pathnames are interpreted relative to the current working +directory. +

-acl +

Defines a list of one or more ACL entries, each a pair that names +

A user name or group name as listed in the Protection Database +
One or more ACL permissions, indicated either by combining the individual +letters or by one of the four acceptable shorthand words +

in that order, separated by a space (thus every instance of this argument +has two parts). The accepted AFS abbreviations and shorthand words, and +the meaning of each, are as follows: +

a +: (administer): change the entries on the ACL +
d +: (delete): remove files and subdirectories from the +directory or move them to other directories +
i +: (insert): add files or subdirectories to the directory by +copying, moving or creating +
k +: (lock): set read locks or write locks on the files in the +directory +
l +: (lookup): list the files and subdirectories in the +directory, stat the directory itself, and issue the fs listacl +command to examine the directory's ACL +
r +: (read): read the contents of files in the directory; +issue the ls -l command to stat the elements in the directory +
w +: (write): modify the contents of files in the directory, +and issue the UNIX chmod command to change their mode bits +
A, B, C, D, E, F, G, H +: Have no default meaning to the AFS server processes, but are made +available for applications to use in controlling access to the +directory's contents in additional ways. The letters must be +uppercase. +
all +: Equals all seven permissions (rlidwka). + + + + +
none +: No permissions. Removes the user/group from the ACL, but does not +guarantee they have no permissions if they belong to groups that remain on the +ACL. + + +
read +: Equals the r (read) and l +(lookup) permissions. + + +
write +: Equals all permissions except a (administer), that +is, rlidwk. + + +

It is acceptable to mix entries that combine the individual letters with +entries that use the shorthand words, but not use both types of notation +within an individual pairing of user or group and permissions. +

To learn the proper format and acceptable values for DFS ACL entries, see +the IBM AFS/DFS Migration Toolkit Administration Guide and +Reference. +

-clear +

Removes all existing entries on each ACL before adding the entries +specified with the -acl argument. +

-negative +

Places the specified ACL entries in the Negative +rights section of each ACL, explicitly denying the rights to the +user or group, even if entries on the accompanying Normal +rights section of the ACL grant them permissions. +

This argument is not supported for DFS files or directories, because DFS +does not implement negative ACL permissions. +

-id +

Places the ACL entries on the Initial Container ACL of each DFS directory, +which are the only file system objects for which this flag is +supported. +

-if +

Places the ACL entries on the Initial Object ACL of each DFS directory, +which are the only file system objects for which this flag is +supported. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example adds two entries to the Normal rights +section of the current working directory's ACL: the first entry +grants r (read) and l (lookup) +permissions to the group pat:friends, while the other (using +the write shorthand) gives all permissions except a +(administer) to the user smith. +

   % fs setacl -dir . -acl pat:friends rl smith write
+   
+   % fs listacl -path .
+   Access list for . is
+   Normal rights:
+      pat:friends rl
+      smith rlidwk
+   
+

The following example includes the -clear flag, which removes +the existing permissions (as displayed with the fs listacl command) +from the current working directory's reports subdirectory and +replaces them with a new set. +

   % fs listacl -dir reports
+   Access list for reports is
+   Normal rights:
+      system:authuser rl
+      pat:friends rlid
+      smith rlidwk
+      pat rlidwka
+   Negative rights:
+      terry rl
+   
+   % fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl
+   
+   % fs listacl -dir reports
+   Access list for reports is
+   Normal rights:
+      system:anyuser rl
+      smith rlidwk
+      pat rlidwka
+   
+

The following example use the -dir and -acl switches +because it sets the ACL for more than one directory (both the current working +directory and its public subdirectory). +

   % fs setacl -dir . public -acl pat:friends rli
+      
+   % fs listacl -path . public
+   Access list for . is
+   Normal rights:
+      pat rlidwka
+      pat:friends rli
+   Access list for public is
+   Normal rights:
+      pat rlidwka
+      pat:friends rli
+   
+

Privilege Required +

The issuer must have the a (administer) permission on +the directory's ACL; the directory's owner and the members of +the system:administrators group have the right implicitly, +even if it does not appear on the ACL. +

Related Information +

fs copyacl +

fs listacl +

IBM AFS/DFS Migration Toolkit Administration Guide and Reference +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf158.htm b/doc/html/AdminReference/auarf158.htm new file mode 100644 index 0000000..7447c8f --- /dev/null +++ b/doc/html/AdminReference/auarf158.htm @@ -0,0 +1,108 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs setcachesize

+ + + + + + + + +

Purpose +

Sets the size of the disk cache +

Synopsis +

fs setcachesize [-blocks <size in 1K byte blocks (0 => reset)>]  
+                [-reset]  [-help]
+    
+fs setca  [-b <size in 1K byte blocks (0 => reset)>]  [-r]  [-h]
+      
+fs cachesize [-b <size in 1K byte blocks (0 => reset)>]  [-r]  [-h]
+  
+fs ca [-b <size in 1K byte blocks (0 => reset)>]  [-r]  [-h]  
+

Description +

The fs setcachesize command changes the number of kilobyte +blocks of local disk space available to the Cache Manager for its data cache, +on machines that use a disk cache. The command is not operative on +machines that use a memory cache. +

To return the cache size to the default value specified in the third field +of the local /usr/vice/etc/cacheinfo file, provide a value of +0 to the -blocks argument. +

To return the cache size to the value set when the machine was last +rebooted, use the -reset flag instead of the -blocks +argument. This is normally the amount specified in the +cacheinfo file, unless the -blocks argument was included +on the afsd command to override the cacheinfo +value. +

To display the current cache size and amount of cache in use, for both disk +and memory caches, use the fs getcacheparms command. +

Cautions +

This command is not operative on machines using a memory cache, and results +in an error message. To change memory cache size, edit the +cacheinfo file and reboot, or reboot and provide the +-blocks argument to the afsd command. +

On machines using a disk cache, do not set the cache size to exceed 85% to +90% of the actual disk space available for the cache directory. The +cache implementation itself requires a small amount of space on the +partition. +

Options +

-blocks +: Specifies the number of one-kilobyte blocks of disk space available for +the Cache Manager to devote to the cache. Provide a value of +0 to set cache size to the default specified in the +cacheinfo file. +
-reset +: Returns the cache size to the value set when the machine was last +booted. This agrees with the value in the cacheinfo file +unless the -blocks argument was used on the afsd +command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command sets the disk cache size to 25000 kilobyte +blocks. +

   % fs setcachesize -blocks 25000
+   
+

Both of the following commands reset the disk cache size to the value in +the cacheinfo file, assuming that the -blocks argument +to the afsd command was not used. +

   % fs setcachesize -blocks 0
+   
+   % fs setcachesize -reset
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

afsd +

fs getcacheparms +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf159.htm b/doc/html/AdminReference/auarf159.htm new file mode 100644 index 0000000..aabf231 --- /dev/null +++ b/doc/html/AdminReference/auarf159.htm @@ -0,0 +1,103 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs setcell

+ + + + + + +

Purpose +

Allows or disallows running of setuid programs from specified cells +

Synopsis +

fs setcell -cell <cell name>⁺  [-suid]  [-nosuid]  [-help]
+   
+fs setce -c <cell name>⁺  [-s]  [-n]  [-h]
+

Description +

The fs setcell command sets whether the Cache Manager allows +programs (and other executable files) from each cell named by the +-cell argument to run with setuid permission. By default, +the Cache Manager allows programs from its home cell to run with setuid +permission, but not programs from any foreign cells. A program belongs +to the same cell as the file server machine that houses the volume in which +the program's binary file resides, as specified in the file server +machine's /usr/afs/etc/ThisCell file. The Cache Manager +determines its own home cell by reading the /usr/vice/etc/ThisCell +file at initialization. +

To enable programs from each specified cell to run with setuid permission, +include the -suid flag. To prohibit programs from running +with setuid permission, include the -nosuid flag, or omit both +flags. +

The fs setcell command directly alters a cell's setuid +status as recorded in kernel memory, so rebooting the machine is +unnecessary. However, non-default settings do not persist across +reboots of the machine unless the appropriate fs setcell command +appears in the machine's AFS initialization file. +

To display a cell's setuid status, issue the fs +getcellstatus command. +

Cautions +

AFS does not recognize effective UID: if a setuid program accesses +AFS files and directories, it does so using the current AFS identity of the +AFS user who initialized the program, not of the program's owner. +Only the local file system recognizes effective UID. +

Only members of the system:administrators group can turn +on the setuid mode bit on an AFS file or directory. +

When the setuid mode bit is turned on, the UNIX ls -l command +displays the third user mode bit as an s instead of an +x. However, the s does not appear on an AFS file +or directory unless setuid permission is enabled for the cell in which the +file resides. +

Options +

-cell +: Names each cell for which to set setuid status. Provide the fully +qualified domain name, or a shortened form that disambiguates it from the +other cells listed in the local /usr/vice/etc/CellServDB +file. +
-suid +: Allows programs from each specified cell to run with setuid +privilege. Provide it or the -nosuid flag, or omit both +flags to disallow programs from running with setuid privilege. +
-nosuid +: Prevents programs from each specified cell from running with setuid +privilege. Provide it or the -suid flag, or omit both flags +to disallow programs form running with setuid privilege. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command enables executable files from the State University +cell to run with setuid privilege on the local machine: +

   % fs setcell -cell stateu.edu -suid
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fs getcellstatus +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf160.htm b/doc/html/AdminReference/auarf160.htm new file mode 100644 index 0000000..40cff7d --- /dev/null +++ b/doc/html/AdminReference/auarf160.htm @@ -0,0 +1,117 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs setclientaddrs

+ + + + + +

Purpose +

Sets the client interfaces to register with the File Server +

Synopsis +

fs setclientaddrs [-address <client network interfaces>⁺]  [-help]
+   
+fs setcl [-a <client network interfaces>⁺]  [-h]
+   
+fs sc [-a <client network interfaces>⁺]  [-h]
+

Description +

The fs setclientaddrs command defines the IP addresses of the +interfaces that the local Cache Manager registers with a File Server when +first establishing a connection to it. +

The list of interfaces specified with this command replaces the list that +the Cache Manager constructs and records in kernel memory as it +initializes. At that time, if the file /usr/vice/etc/NetInfo +exists on the client machine's local disk, the Cache Manager uses its +contents as the basis for the list of interfaces addresses. If the file +does not exist, the Cache Manager instead uses the network interfaces +configured with the operating system. It then removes from the list any +address included in the local /usr/vice/etc/NetRestrict +file. It records the final list in kernel memory. (An +administrator must create the NetInfo and NetRestrict +files; there are no default versions of them.) +

To list the interfaces that the Cache Manager is currently registering with +File Servers, use the fs getclientaddrs command. +

Cautions +

The list specified with this command persists in kernel memory only until +the client machine reboots. To preserve it across reboots, either list +the interfaces in the local /usr/vice/etc/NetInfo file, or place +the appropriate fs setclientaddrs command in the machine's AFS +initialization script. +

Changes made with this command do not propagate automatically to File +Servers to which the Cache Manager has already established a +connection. To force such File Servers to use the revised list, either +reboot each file server machine, or change the NetInfo file and +reboot the client machine. +

The fs command interpreter verifies that each of the addresses +specified as a value for the -address argument is actually +configured with the operating system on the client machine. If it is +not, the command fails with an error message that marks the address as a +Nonexistent interface. +

Options +

-address +: Specifies each IP address to place in the list of interfaces, in dotted +decimal format. Hostnames are not acceptable. Separate each +address with one or more spaces. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The message +

   Adding interface
+   
+

confirms that each new interface was added to the Cache Manager's +list. The address appears in hexadecimal format to match the notation +used in the File Server log, /usr/afs/logs/FileLog. +

Examples +

The following example sets the two interfaces that the Cache Manager +registers with File Servers. +

   % fs setclientaddrs 191.255.105.68 191.255.108.84
+   Adding 0xbfff6944
+   Adding 0xbfff6c54
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fs getclientaddrs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf161.htm b/doc/html/AdminReference/auarf161.htm new file mode 100644 index 0000000..d7873d9 --- /dev/null +++ b/doc/html/AdminReference/auarf161.htm @@ -0,0 +1,92 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs setquota

+ + + + + +

Purpose +

Sets the maximum quota for the volume containing a file or directory +

Synopsis +

fs setquota [-path <dir/file path>]  -max <max quota in kbytes>  [-help]
+   
+fs setq [-p <dir/file path>]  -m <max quota in kbytes>  [-h] 
+   
+fs sq [-p <dir/file path>]  -m <max quota in kbytes>  [-h] 
+

Description +

The fs setquota command sets the quota (maximum possible size) +of the read/write volume that contains the directory or file named by the +-path argument. +

To set the quota on multiple volumes at the same time, use the fs +setvol command. +

To display a volume's quota, use the fs examine, fs +listquota or fs quota command. +

Options +

-path +

Names the directory or file for which to set the host volume's +quota. Partial pathnames are interpreted relative to the current +working directory, which is also the default value if this argument is +omitted. +

Specify the read/write path to the file or directory, to avoid the failure +that results from attempting to change 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 +fs mkmount reference page. +

-max +

Sets the maximum amount of file server disk space the volume can +occupy. Specify the number of one-kilobyte blocks as a positive integer +(1024 is one megabyte). A value of 0 sets an +unlimited quota, but the size of the disk partition that houses the volume +places an absolute limit on the volume's size. +

If the -path argument is omitted (to set the quota of the volume +housing the current working directory), the -max switch must be +included with this argument. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command imposes a maximum quota of 3000 kilobytes on the +volume that houses the /afs/abc.com/usr/smith +directory: +

   % fs setquota -path /afs/abc.com/usr/smith -max 3000
+   
+

Privilege Required +

The issuer must belong to the system:administrators +group. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf162.htm b/doc/html/AdminReference/auarf162.htm new file mode 100644 index 0000000..435639b --- /dev/null +++ b/doc/html/AdminReference/auarf162.htm @@ -0,0 +1,270 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs setserverprefs

+ + + + + + + +

Purpose +

Sets the Cache Manager's preference ranks for file server or VL Server +machines +

Synopsis +

fs setserverprefs [-servers <fileserver names and ranks>⁺]
+                  [-vlservers <VL server names and ranks>⁺]
+                  [-file <input from named file>]  [-stdin]  [-help]
+   
+fs sets [-se <fileserver names and ranks>⁺]  [-vl <VL server names and ranks>⁺]
+        [-f <input from named file>]  [-st]  [-h]
+   
+fs sp [-se <fileserver names and ranks>⁺]  [-vl <VL server names and ranks>⁺]  
+      [-f <input from named file>]  [-st]  [-h]
+

Description +

The fs setserverprefs command sets the local Cache +Manager's preference ranks for one or more file server machine interfaces +or, if the -vlserver argument is provided, for Volume Location (VL) +Server machines. For file server machines, the numerical ranks +determine the order in which the Cache Manager attempts to contact the +interfaces of machines that are housing a volume. For VL Server +machines, the ranks determine the order in which the Cache Manager attempts to +contact a cell's VL Servers when requesting VLDB information. +

The fs getserverprefs reference page explains how the Cache +Manager uses preference ranks when contacting file server machines or VL +Server machines. The following paragraphs explain how the Cache Manager +calculates default ranks, and how to use this command to change the +defaults. +

Calculation of Default Preference Ranks +

The Cache Manager stores a preference rank in kernel memory as a paired IP +address and numerical rank. If a file server machine is multihomed, the +Cache Manager assigns a distinct rank to each of the machine's addresses +(up to the number of addresses that the VLDB can store per machine, which is +specified in the IBM AFS Release Notes). Once calculated, a +rank persists until the machine reboots, or until this command is used to +change it. +

The Cache Manager sets default VL Server preference ranks as it +initializes, randomly assigning a rank from the range 10,000 to 10,126 to each +of the machines listed in the local /usr/vice/etc/CellServDB +file. Machines from different cells can have the same rank, but this +does not present a problem because the Cache Manager consults only one +cell's ranks at a time. +

The Cache Manager sets default preference ranks for file server machine as +it fetches volume location information from the VLDB. Each time it +learns about file server machine interfaces for which it has not already set +ranks, it assigns a rank to each interface. If the local client machine +has only one IP address, the Cache Manager compares it to the server +interface's IP address and sets a rank according to the following +algorithm. If the client machine is multihomed, the Cache Manager +applies the algorithm to each of the client machine's addresses and +assigns to the file server machine interface the lowest rank that +results. +

If the local machine is a file server machine, the base rank for each of +its interfaces is 5,000. +
If the file server machine interface is on the same subnetwork as the +client interface, its base rank is 20,000. +
If the file server machine interface is on the same network as the client +interface, or is at the distant end of a point-to-point link with the client +interface, its base rank is 30,000. +
If the file server machine interface is on a different network than the +client interface, or the Cache Manager cannot obtain network information about +it, its base rank is 40,000. +

After assigning a base rank to a file server machine interface, the Cache +Manager adds to it a number randomly chosen from the range 0 (zero) to +14. As an example, a file server machine interface in the same +subnetwork as the local machine receives a base rank of 20,000, but the Cache +Manager records the actual rank as an integer between 20,000 and +20,014. This process reduces the number of interfaces that have exactly +the same rank. As with VL Server machine ranks, it is possible for file +server machine interfaces from foreign cells to have the same rank as +interfaces in the local cell, but this does not present a problem. Only +the relative ranks of the interfaces that house a given volume are relevant, +and AFS only supports storage of a volume in one cell at a time. +

Setting Non-default Preference Ranks +

Use the fs setserverprefs command to reset an existing +preference rank, or to set the initial rank of a file server machine interface +or VL Server machine for which the Cache Manager has no rank. To make a +rank persist across a reboot of the local machine, place the appropriate +fs setserverprefs command in the machine's AFS initialization +file. +

Specify each preference rank as a pair of values separated by one or more +spaces: +

The first member of the pair is the fully-qualified hostname (for example, +fs1.abc.com), or the IP address in dotted decimal +format, of a file server machine interface or VL Server machine +
The second member of the pair is an integer. The possible ranks +range from 1 through 65535. +

As with default ranks, the Cache Manager adds a randomly chosen integer to +a rank specified by this command. For file server machine interfaces, +the integer is from the range 0 (zero) to 14; for VL Server machines, it +is from the range 0 (zero) to 126. For example, if the administrator +assigns a rank of 15,000 to a file server machine interface, the Cache Manager +stores an integer between 15,000 to 15,014. +

There are several ways to provide ranks for file server machine interfaces +(but not for VL Server machines): +

On the command line, following the -servers argument. +
In a file named by the -file argument. Place each pair +on its own line in the file. Directing the output from the fs +getserverprefs command to a file automatically generates a file with the +proper format. +
Via the standard input stream, by providing the -stdin +flag. This method enables the issuer to feed in values directly from a +program or script that generates preference ranks by using an algorithm +appropriate to the local cell. The AFS distribution does not include +such programs or scripts. +

When setting file server machine preference ranks, it is legal to combine +the -servers, -file, and -stdin options on a +single command line. If different options specify a different rank for +the same interface, the Cache Manager stores and uses the rank assigned with +the -servers argument. +

The -vlservers argument is the only way to assign VL Server +machine ranks. It can be combined with one or more of the +-servers, -file, and -stdin options, but the +Cache Manager applies the values provided for those options to file server +machine ranks only. +

The fs command interpreter does not verify hostnames or IP +addresses, and so assigns preference ranks to invalid machine names or +addresses. The Cache Manager never uses such ranks unless the same +incorrect information is in the VLDB. +

Options +

-servers +

Specifies one or more file server machine preference ranks. Each +rank pairs the fully-qualified hostname or IP address (in dotted decimal +format) of a file server machine's interface with an integer rank, +separated by one or more spaces; also separate each pair with one or more +spaces. Acceptable values for the rank range from 1 through +65521; a lower value indicates a greater preference. +Providing ranks outside this range can have unpredictable results. +Providing a value no larger than 65521 guarantees that the rank +does not exceed the maximum possible value of 65,535 even if the largest +random factor (14) is added. +

This argument can be combined with the -file argument, +-stdin flag, or both. If more than one of the arguments sets +a rank for the same interface, the rank set by this argument takes +precedence. It can also be combined with the -vlservers +argument, but does not interact with it. +

-vlservers +

Specifies one or more VL Server preference ranks. Each rank pairs +the fully-qualified hostname or IP address (in dotted decimal format) of a VL +Server machine with an integer rank, separated by one or more spaces; +also separate each pair with one or more spaces. Acceptable values for +the rank range from 1 through 65521; a lower value +indicates a greater preference. Providing ranks outside this range can +have unpredictable results. Providing a value no larger than +65521 guarantees that the rank does not exceed the maximum possible +value of 65,535 even if the largest random factor (14) is added. +

This argument can be combined with the -servers argument, +-file argument, -stdin flag, or any combination of the +three, but does not interact with any of them. They apply only to file +server machine ranks. +

-file +

Specifies the full pathname of a file from which to read pairs of file +server machine interfaces and their ranks, using the same notation and range +of values as for the -servers argument. In the file, place +each pair on its own line and separate the two parts of each pair with one or +more spaces. +

This argument can be combined with the -servers argument, +-stdin flag, or both. If more than one of the arguments sets +a rank for the same interface, the rank set by the -server argument +takes precedence. It can also be combined with the +-vlservers argument, but does not interact with it. +

-stdin +

Reads pairs of file server machine interface and integer rank from the +standard input stream. The intended use is to accept input piped in +from a user-defined program or script that generates ranks in the appropriate +format, but it also accepts input typed to the shell. Format the +interface and rank pairs as for the -file argument. If +typing at the shell, type <Ctrl-d> after the final newline to +complete the input. +

This argument can be combined with the -servers argument, the +-file argument, or both. If more than one of the arguments +sets a rank for the same interface, the rank set by the -server +argument takes precedence. It can also be combined with the +-vlservers argument, but does not interact with it. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command sets the Cache Manager's preference ranks for +the file server machines named fs3.abc.com and +fs4.abc.com, the latter of which is specified by its +IP address, 192.12.105.100. The machines reside in +another subnetwork of the local machine's network, so their default base +rank is 30,000. To increase the Cache Manager's preference for +these machines, the issuer assigns a rank of 25000, to which the +Cache Manager adds an integer in the range from 0 to 15. +

   # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000
+   
+

The following command uses the -servers argument to set the +Cache Manager's preference ranks for the same two file server machines, +but it also uses the -file argument to read a collection of +preference ranks from a file that resides in the local file +/etc/fs.prefs: +

   # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000  \ 
+                       -file /etc/fs.prefs
+   
+

The /etc/fs.prefs file has the following contents and +format: +

   192.12.108.214        7500
+   192.12.108.212        7500
+   138.255.33.41         39000
+   138.255.33.34         39000
+   128.0.45.36           41000
+   128.0.45.37           41000
+   
+

The following command uses the -stdin flag to read preference +ranks from the standard input stream. The ranks are piped to the +command from a program, calc_prefs, which was written by the issuer +to calculate preferences based on values significant to the local cell. +

   # calc_prefs | fs setserverprefs -stdin
+   
+

The following command uses the -vlservers argument to set the +Cache Manager's preferences for the VL server machines named +fs1.abc.com, fs3.abc.com, +and fs4.abc.com to base ranks of 1, 11000, and 65521, +respectively: +

   # fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000  \
+                       fs4.abc.com 65521
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fs getserverprefs +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf163.htm b/doc/html/AdminReference/auarf163.htm new file mode 100644 index 0000000..834e736 --- /dev/null +++ b/doc/html/AdminReference/auarf163.htm @@ -0,0 +1,108 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs setvol

+ + + + + + + +

Purpose +

Set maximum quota and messages for the volume containing a file or +directory +

Synopsis +

fs setvol [-path <dir/file path>⁺]  [-max <disk space quota in 1K units>]
+          [-offlinemsg <offline message>]  [-help]
+   
+fs setv [-p <dir/file path>⁺]  [-ma <disk space quota in 1K  units>] 
+        [-o <offline message>]  [-h]
+    
+fs sv [-p <dir/file path>⁺]  [-ma <disk space quota in 1K units>] 
+      [-o <offline message>]  [-h]
+

Description +

The fs setvol command sets the quota (maximum possible size) of +the read/write volume that contains each directory or file named by the +-path argument. To associate a message with the volume which +then appears in the output of the fs examine command, include the +-offlinemsg argument. +

To display all of the settings made with this command, use the fs +examine command. The fs listquota command reports a +fileset's quota, and the fs quota command the percent of quota +used. +

To set quota on one volume at a time, use the fs setquota +command. +

Options +

-path +

Names each file or directory for which to set the host volume's quota +and offline message. Partial pathnames are interpreted relative to the +current working directory, which is also the default value if this argument is +omitted. +

-max +

Sets the maximum amount of file server disk space the volume can +occupy. Provide a positive integer to indicate the number of +one-kilobyte blocks (1024 is one megabyte). A value of +0 sets an unlimited quota, but the size of the disk partition that +houses the volume places an absolute limit on the volume's size. +

If the -path argument is omitted (so that the command sets the +quota of the volume housing the current working directory), the +-max switch must be provided. +

-offlinemsg +

Associates a message with the volume which then appears in the output of +the fs examine command. Its intended use is to explain why +the volume is currently offline. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command imposes a 6500 kilobyte quota on the volumes mounted +at the home directories /afs/abc.com/usr/smith and +/afs/abc.com/usr/pat: +

   % cd /afs/abc.com/usr
+    
+   % fs setvol -path smith pat -max 6500
+   
+

Privilege Required +

The issuer must belong to the system:administrators +group. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf164.htm b/doc/html/AdminReference/auarf164.htm new file mode 100644 index 0000000..a67d216 --- /dev/null +++ b/doc/html/AdminReference/auarf164.htm @@ -0,0 +1,205 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs storebehind

+ + +

Purpose +

Enables asynchronous writes to the file server +

Synopsis +

fs storebehind [-kbytes <asynchrony for specified names>]  
+               [-files <specific pathnames>⁺]  
+               [-allfiles <new default (KB)>]  [-verbose]  [-help]
+    
+fs st [-k <asynchrony for specified names>]  [-f <specific pathnames>⁺]  
+      [-a <new default (KB)>]  [-v]  [-h]
+

Description +

The fs storebehind command enables the Cache Manager to perform +a delayed asynchronous write to the File Server when an application closes a +file. By default, the Cache Manager writes all data to the File Server +immediately and synchronously when an application program closes a +file--that is, the close system call does not return until the +Cache Manager has actually transferred the final chunk of the file to the File +Server. This command specifies the number of kilobytes of a file that +can still remain to be written to the File Server when the Cache Manager +returns control to the application. It is useful if users working on +the machine commonly work with very large files, but also introduces the +complications discussed in the Cautions section. +

Set either or both of the following in a single command: +

To set a value that applies to all AFS files manipulated by applications +running on the machine, use the -allfiles argument. This +value is termed the default store asynchrony for the machine, and +persists until the machine reboots. If it is not set, the default value +is zero, indicating that the Cache Manager performs synchronous writes. +
+
As an example, the following setting means that when an application closes +a file, the Cache Manager can return control to the application as soon as no +more than 10 kilobytes of the file remain to be written to the File +Server. +
```
   -allfiles 10
+   
+
```
+
To set a value that applies to one or more individual files, and overrides +the value of the -allfiles argument for them, combine the +-kbytes and -files arguments. The setting +persists as long as there is an entry for the file in the kernel table that +the Cache Manager uses to track certain information about files. In +general, such an entry persists at least until an application closes the file +or exits, but the Cache Manager is free to recycle the entry if the file is +inactive and it needs to free up slots in the table. To increase the +certainty that there is an entry for the file in the table, issue the fs +storebehind command shortly before closing the file. +
As an example, the following setting means that when an application closes +either of the files bigfile and biggerfile, the Cache +Manager can return control to the application as soon as no more than a +megabyte of the file remains to be written to the File Server. +
```
   -kbytes 1024 -files bigfile biggerfile
+   
+
```
+
Note that once an explicit value has been set for a file, the only way to +make it subject to the default store asynchrony once again is to set +-kbytes to that value. In other words, there is no +combination of arguments that automatically makes a file subject to the +default store asynchrony once another value has been set for the file. +

To display the settings that currently apply to individual files or to all +files, provide the command's arguments in certain combinations as +specified in the Output section of this reference page. +

Cautions +

For the following reasons, use of this command is not recommended in most +cases. +

In normal circumstances, an asynchronous setting results in the Cache +Manager returning control to applications earlier than it otherwise does, but +this is not guaranteed. +

If a delayed write fails, there is no way to notify the application, since +the close system call has already returned with a code indicating +success. +

Writing asynchronously increases the possibility that the user will not +notice if a write operation makes the volume that houses the file exceed its +quota. As always, the portion of the file that exceeds the +volume's quota is lost, which prompts a message such as the +following: +

   No space left on device
+   
+

To avoid losing data, it is advisable to verify that the volume housing the +file has space available for the amount of data anticipated to be +written. +

Options +

-kbytes +: Specifies the number of kilobytes of data from each file named by the +-files argument that can remain to be written to the file server +when the Cache Manager returns control to an application program that closed +the file. The -files argument is required along with this +argument. Provide an integer from the range 0 (which +reinstates the Cache Manager's default behavior or writing synchronously) +to the maximum AFS file size. +
-files +: Names each file to which the value set with the -kbytes +argument applies. The setting persists as long as there is an entry for +the file in the kernel table that the Cache Manager uses to track certain +information about files. Because closing a file generally erases the +entry, when reopening a file the only way to guarantee that the setting still +applies is to reissue the command. If this argument is provided without +the -kbytes argument, the command reports the current setting for +the specified files, and the default store asynchrony. +
-allfiles +: Sets the default store asynchrony for the local machine, which is the +number of kilobytes of data that can remain to be written to the file server +when the Cache Manager returns control to the application program that closed +a file. The value applies to all AFS files manipulated by applications +running on the machine, except those for which settings have been made with +the -kbytes and -files arguments. Provide an +integer from the range 0 (which indicates the default of +synchronous writes) to the maximum AFS file size. +
-verbose +: Produces output confirming the settings made with the accompanying +-kbytes and -files arguments, the -allfiles +argument, or all three. If provided by itself, reports the current +default store asynchrony. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

If none of the command's options are included, or if only the +-verbose flag is included, the following message reports the +default store asynchrony (the setting that applies to all files manipulated by +applications running on the local machine and for which not more specific +asynchrony is set). +

   Default store asynchrony is x kbytes.
+   
+

A value of 0 (zero) indicates synchronous writes and is the +default if no one has included the -allfiles argument on this +command since the machine last rebooted. +

If the -files argument is provided without the +-kbytes argument, the output reports the value that applies to each +specified file along with the default store asynchrony. If a particular +value has previously been set for a file, the following message reports +it: +

   Will store up to y kbytes of file asynchronously.
+   Default store asynchrony is x kbytes.
+   
+

If the default store asynchrony applies to a file because no explicit +-kbytes value has been set for it, the message is instead as +follows: +

   Will store file according to default.
+   Default store asynchrony is x kbytes.
+   
+

If the -verbose flag is combined with arguments that set values +(-files and -kbytes, or -allfiles, or all +three), there is a message that confirms immediately that the setting has +taken effect. When included without other arguments or flags, the +-verbose flag reports the default store asynchrony only. +

Examples +

The following command enables the Cache Manager to return control to the +application program that closed the file test.data when 100 +kilobytes still remain to be written to the File Server. The +-verbose flag produces output that confirms the new setting, and +that the default store asynchrony is zero. +

   % fs storebehind -kbytes 100 -files test.data -verbose
+   Will store up to 100 kbytes of test.data asynchronously.
+   Default store asynchrony is 0 kbytes.
+   
+

Privilege Required +

To include the -allfiles argument, the issuer must be logged in +as the local superuser root. +

To include the -kbytes and -files arguments, the +issuer must either be logged in as the local superuser root or have +the w (write) permission on the ACL of each file's +directory. +

To view the current settings (by including no arguments, the +-file argument alone, or the -verbose argument alone), +no privilege is required. +

Related Information +

afsd +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf165.htm b/doc/html/AdminReference/auarf165.htm new file mode 100644 index 0000000..793fc1c --- /dev/null +++ b/doc/html/AdminReference/auarf165.htm @@ -0,0 +1,106 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs sysname

+ + + + + + + + + + + + + + +

Purpose +

Reports or sets the CPU/operating system type +

Synopsis +

fs sysname [-newsys <new sysname>]  [-help]
+    
+fs sy [-n <new sysname>]  [-h]
+

Description +

The fs sysname command sets or displays the local machine's +CPU/operating system type as recorded in kernel memory. The Cache +Manager substitutes the string for the @sys variable which can occur +in AFS pathnames; the IBM AFS Quick Beginnings and IBM +AFS Administration Guide explain how using @sys can simplify +cell configuration. It is best to use it sparingly, however, because it +can make the effect of changing directories unpredictable. +

The command always applies to the local machine only. If issued on +an NFS client machine accessing AFS via the NFS/AFS Translator, the string is +set or reported for the NFS client machine. The Cache Manager on the +AFS client machine serving as the NFS client's NFS/AFS translator machine +stores the value in its kernel memory, and so can provide the NFS client with +the proper version of program binaries when the user issues commands for which +the pathname to the binaries includes @sys. There is a +separate record for each user logged into the NFS client, which implies that +if a user adopts a new identity (UNIX UID) during a login session on the NFS +client--perhaps by using the UNIX su command--he or she +must verify that the correct string is set for the new identity also. +

Options +

-newsys +: Sets the CPU/operating system indicator string for the local +machine. If this argument is omitted, the output displays the current +setting instead. AFS uses a standardized set of strings; consult +the IBM AFS Quick Beginnings or AFS Release +Notes. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

When the -newsys argument is omitted, the output reports the +machine's system type in the following format: +

   Current sysname is 'system_type'
+   
+

Examples +

The following example shows the output produced on a Sun SPARCStation +running Solaris 5.7: +

   % fs sysname
+   Current sysname is 'sun4x_57'
+   
+

The following command defines a machine to be a IBM RS/6000 running AIX +4.2: +

   % fs sysname -newsys rs_aix42
+   
+

Privilege Required +

To display the current setting, no privilege is required. To include +the -newsys argument on an AFS client machine, the issuer must be +logged in as the local superuser root. +

Related Information +

fs exportafs +

sys +

IBM AFS Quick Beginnings +

IBM AFS Administration Guide +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf166.htm b/doc/html/AdminReference/auarf166.htm new file mode 100644 index 0000000..570e0ce --- /dev/null +++ b/doc/html/AdminReference/auarf166.htm @@ -0,0 +1,80 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs whereis

+ + + + + + + +

Purpose +

Reports the name of each file server machine housing a file or directory +

Synopsis +

fs whereis [-path <dir/file path>⁺]  [-help]
+   
+fs whe [-p <dir/file path>⁺]  [-h]
+

Description +

The fs whereis command returns the name of each file server +machine that houses the volume containing each directory or file named by the +-path argument. +

Options +

-path +: Names each AFS file or directory for which to return the host file server +machine. Partial pathnames are interpreted relative to the current +working directory, which is also the default value if this argument is +omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output includes a line for each specified directory or file. It +names the file server machine on which the volume that houses the specified +directory or file resides. A list of multiple machines indicates that +the directory or file is in a replicated volume. +

Machine names usually have a suffix indicating their cell +membership. If the cell is not clear, use the fs whichcell +command to display the cell in which the directory or file resides. To +display the cell membership of the local machine, use the fs wscell +command. +

Examples +

The following example indicates that volume housing the directory +/afs/abc.com resides is replicated on both +fs1.abc.com and +fs3.abc.com: +

   % fs whereis -path /afs/abc.com
+   File /afs/abc.com is on hosts fs1.abc.com fs3.abc.com
+   
+

Privilege Required +

None +

Related Information +

fs whichcell +

fs wscell +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf167.htm b/doc/html/AdminReference/auarf167.htm new file mode 100644 index 0000000..51f4a6f --- /dev/null +++ b/doc/html/AdminReference/auarf167.htm @@ -0,0 +1,74 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs whichcell

+ + + + + + + +

Purpose +

Returns the name of the cell to which a file or directory belongs +

Synopsis +

fs whichcell [-path <dir/file path>⁺]  [-help]
+   
+fs whi  [-p <dir/file path>⁺]  [-h]
+

Description +

The fs whichcell command returns the name of the cell in which +the volume that houses each indicated directory or file resides. +

To display the file server machine on which the volume housing a directory +or file resides, use the fs whichcell command. To display +the cell membership of the local machine, use the fs wscell +command. +

Options +

-path +: Names each AFS file or directory for which to return the cell +membership. Partial pathnames are interpreted relative to the current +working directory, which is also the default value if this argument is +omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output includes a line for each directory or file, naming the cell to +which the volume that houses the directory or file resides. +

Examples +

The following example shows that the current working directory resides in a +volume in the ABC Corporation cell: +

   % fs whichcell
+   File . lives in cell 'abc.com'
+   
+

Privilege Required +

None +

Related Information +

fs wscell +

fs whereis +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf168.htm b/doc/html/AdminReference/auarf168.htm new file mode 100644 index 0000000..0bed0f4 --- /dev/null +++ b/doc/html/AdminReference/auarf168.htm @@ -0,0 +1,67 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fs wscell

+ + + + + + +

Purpose +

Returns the name of the cell to which a machine belongs +

Synopsis +

fs wscell [-help]
+   
+fs ws [-h]
+

Description +

The fs wscell command returns the name of the local +machine's home cell. +

Options +

-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output displays the contents of the local +/usr/vice/etc/ThisCell file, in the format +

   This workstation belongs to cell 'cellname'
+   
+

Examples +

The following example results when the fs wscell is issued on a +machine in the State University cell: +

   % fs wscell
+   This workstation belongs to cell 'stateu.edu'
+    
+

Privilege Required +

None +

Related Information +

fs whereis +

fs whichcell +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf169.htm b/doc/html/AdminReference/auarf169.htm new file mode 100644 index 0000000..f9c454d --- /dev/null +++ b/doc/html/AdminReference/auarf169.htm @@ -0,0 +1,89 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace

Purpose + + + + + + +

Introduction to the fstrace command suite +

Description +

The commands in the fstrace command suite are the interface that +system administrators employ to trace Cache Manager operations for debugging +purposes. Examples of Cache Manager operations are fetching file data +or the status information used to produce output for the UNIX ls +command. +

The fstrace command interpreter defines an extensive set of +Cache Manager operations as the cm event set. +When the event set is activated, the Cache Manager writes a message to the +cmfx trace log in kernel memory each time it performs +one of the defined operations. The log expands only to a defined size +(by default, 60 KB), after which it is overwritten in a circular fashion (new +trace messages overwrite the oldest ones). If an operation of +particular interest occurs, the administrator can afterward display the log on +the standard output stream or write it to a file for later study. For +more specific procedural instructions, see the IBM AFS Administration +Guide. +

There are several categories of commands in the fstrace command +suite: +

Commands to administer or display information about the trace log: +
fstrace clear, fstrace lslog, fstrace +setlog +
Commands to set or display the status of the event set: +
fstrace lsset and fstrace setset +
A command to display the contents of the trace log: fstrace +dump +
Commands to obtain help: fstrace apropos and fstrace +help +

Options +

All fstrace commands accept the following optional flag. +It is listed in the command descriptions and described in detail here: + +

-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. +

Privilege Required +

To issue most fstrace commands, the issuer must be logged on as +the local superuser root on the machine that is generating the +trace log. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf170.htm b/doc/html/AdminReference/auarf170.htm new file mode 100644 index 0000000..6eb60b7 --- /dev/null +++ b/doc/html/AdminReference/auarf170.htm @@ -0,0 +1,74 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace apropos

Purpose + + + +

Displays each help entry containing a keyword string +

Synopsis +

fstrace apropos -topic <help string>  [-help]
+   
+fstrace ap -t <help string>  [-h]
+

Description +

The fstrace apropos command displays the first line of the +online help entry for any fstrace command that contains in its name +or short description the string specified with the -topic +argument. +

To display a command's complete syntax, use the fstrace +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 +fstrace command where the string specified with the +-topic argument is part of the command name or first line. +

Examples +

The following command lists all fstrace commands that include +the word set in their names or short descriptions: +

   % fstrace apropos set
+   clear: clear logs by logname or by event set
+   lsset: list available event sets
+   setlog: set the size of a log
+   setset: set state of event sets
+   
+

Privilege Required +

None +

Related Information +

fstrace help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf171.htm b/doc/html/AdminReference/auarf171.htm new file mode 100644 index 0000000..e14a9b3 --- /dev/null +++ b/doc/html/AdminReference/auarf171.htm @@ -0,0 +1,65 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace clear

Purpose +

Clears the trace log +

Synopsis +

fstrace clear [-set <set_name>⁺]  [-log <log_name>⁺]  [-help] 
+           
+fstrace c [-s <set_name>⁺]  [-l <log_name>⁺]  [-h]
+

Description +

The fstrace clear command erases the contents of the trace log +from kernel memory, but leaves kernel memory allocated for the log. +

Options +

-set +: Names the event set for which to clear the associated trace log. +The only acceptable value is cm (for which the associated trace log +is cmfx). Provide either this argument or the +-log argument, or omit both to clear the cmfx log by +default. +
-log +: Names the trace log to clear. The only acceptable value is +cmfx. Provide either this argument or the -set +argument, or omit both to clear the cmfx log by default. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command clears the cmfx trace log on the local +machine: +

   # fstrace clear
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fstrace lslog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf172.htm b/doc/html/AdminReference/auarf172.htm new file mode 100644 index 0000000..62ba54e --- /dev/null +++ b/doc/html/AdminReference/auarf172.htm @@ -0,0 +1,208 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace dump

Purpose + + +

Dumps a trace log +

Synopsis +

fstrace dump [-set <set_name>⁺]  [-follow <log_name>]  
+             [-file <output_filename>]  
+             [-sleep <seconds_between_reads>]  [-help]
+   
+fstrace d [-se <set_name>⁺]  [-fo <log_name>]  [-fi <output_filename>] 
+          [-sl <seconds_between_reads>]  [-h]
+

Description +

The fstrace dump command displays the current contents of the +cmfx trace log on the standard output stream or writes it to the +file named by the -file argument. +

To write the log continuously to the standard output stream or to a file, +use the -follow argument. By default, the log's +contents are written out every ten seconds and then automatically +cleared. To change the interval between writes, use the +-sleep argument. +

Cautions +

This command produces output only if the cm event set is +active. To display or set the event set's state, use the +fstrace lsset or fstrace setset command +respectively. +

To make the output from this command maximally readable, the message +catalog file called afszcm.cat must reside in the local +/usr/vice/etc/C directory. If necessary, copy the file to +that directory from the AFS Binary Distribution before activating +tracing. +

When the cm event set is active, a defined amount of kernel +memory (by default, 60 KB) is allocated for the cmfx trace +log. As described on the introductory fstrace reference +page, when the buffer is full, messages are overwritten in a circular fashion +(new messages overwrite the oldest ones). To allocate more kernel +memory for the log, use the fstrace setlog command; to display +the log buffer's current size, use the fstrace lslog command +with the -long argument. +

Options +

-set +

Names the event set for which to write out the associated trace +log. The only acceptable value is cm (for which the +associated trace log is cmfx). Provide either this argument +or the -log argument, or omit both to write out the cmfx +log by default. +

-follow +

Names the trace log to write out continuously at a specified interval (by +default, every ten seconds; use the -sleep argument to change +the interval). The log is cleared after each write operation. +

The only acceptable value is cmfx. Provide either this +argument or the -set argument, or omit both to write out the +cmfx log by default. +

-file +

Specifies the pathname of the file to which to write the trace log's +contents. It can be in AFS or on the local disk. Partial +pathnames are interpreted relative to the current working directory. If +this argument is omitted, the trace log appears on the standard output +stream. +

-sleep +

Sets the number of seconds between writes of the trace log's contents +when it is dumped continuously. Provide the -follow argument +along with this one. If this argument is omitted, the default interval +is ten seconds. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The output begins with a header specifying the date and time at which the +write operation began. If the -follow argument is not +included, the header also reports the number of logs being dumped; it is +always 1, since there is only the cmfx trace log. +The format of the header is as follows: +

   AFS Trace Dump -
+     Date: starting_timestamp
+   Found 1 logs.
+   Contents of log cmfx:
+   
+

Each subsequent message describes a Cache Manager operation in the +following format: +

   time timestamp, pid pid:event_message
+   
+

where +

timestamp +: Specifies the time at which the Cache Manager performed the operation, as +the number of seconds since the dump began +
pid +: Specifies the process ID of the process or thread associated with the +message +
event_message +: Is the message itself. They are generally meaningful only to +someone familiar with the AFS source code. +

In addition, every 1024 seconds the fstrace command interpreter +writes a message that records the current clock time, in the following +format: +

   time timestamp, pid pid: Current time: unix_time
+   
+

where +

timestamp +: Is the number of seconds from the start of trace logging +
pid +: Is the process ID number +
unix_time +: Is the machine's clock time, represent in the standard UNIX time +format as the number of seconds since midnight on January 1, 1970. +

Use this message to determine the actual clock time associated with each +log message. Determine the actual time as follows: +

Locate the message of interest. +
Search backward through the trace file for the closest current time +message. +
If the current time message's timestamp is smaller than the +log message's timestamp, subtract former from the latter. +If the current time message's timestamp is larger than the log +message's timestamp, add 1024 to the latter and subtract the +former from the result. +
Add the resulting number to the current time message's +unix_time to determine the log message's actual time. +

If any of the data in the kernel trace buffer has been overwritten since +tracing was activated, the following message appears at the appropriate place +in the output: +

   Log wrapped; data missing.
+   
+

To reduce the likelihood of overwriting, use the fstrace setlog +command to increase the kernel buffer's size. To display the +current defined buffer size, use the fstrace lslog command with the +-long argument. +

The following message at the end of the log dump indicates that it is +completed: +

   AFS Trace Dump - Completed
+   
+

Examples +

The following command dumps the log associated with the cm event +set to the standard output stream. +

   # fstrace dump -set cm
+   AFS Trace Dump -
+      Date: Tue Apr  7 10:54:57 1998
+   Found 1 logs.
+   time 32.965783, pid 0: Tue Apr  7 10:45:52 1998
+   time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20 
+   time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0) 
+   time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0)
+   time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0)
+                                    .
+                                    .
+                                    .
+   time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \
+        fid (756 4fb7e:588d240.2ff978a8.6) 
+   time 71.440569, pid 33658: Returning code 2 from 19 
+   time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2) 
+   time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0) 
+   AFS Trace Dump - Completed
+   
+

The following command dumps the trace log associated with the cm +event set on the local machine to the file +cmfx.dump.file.1, using the default interval +of 10 seconds between successive dumps: +

   # fstrace dump -follow cmfx -file cmfx.dump.file.1
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf173.htm b/doc/html/AdminReference/auarf173.htm new file mode 100644 index 0000000..79a37c6 --- /dev/null +++ b/doc/html/AdminReference/auarf173.htm @@ -0,0 +1,86 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace help

Purpose + + + +

Displays the syntax of specified fstrace commands or lists +functional descriptions of all fstrace commands +

Synopsis +

fstrace help [-topic <help string>⁺]  [-help] 
+    
+fstrace h [-t <help string>⁺]  [-h] 
+

Description +

The fstrace help command displays the complete online help entry +(short description and syntax statement) for each command operation code +specified by the -topic argument. If the -topic +argument is omitted, the output includes the first line (name and short +description) of the online help entry for every fstrace +command. +

To list every fstrace command whose name or short description +includes a specified keyword, use the fstrace apropos +command. +

Options +

-topic +: Indicates each command for which to display the complete online help +entry. Omit the fstrace part of the command name, providing +only the operation code (for example, specify clear, not +fstrace clear). If this argument is omitted, the output +briefly describes every fstrace command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each fstrace command consists of two +or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following command displays the online help entry for the fstrace +setset command: +

   % fstrace help -topic setset
+   fstrace setset: set state of event sets 
+   Usage: fstrace setset [-set <set_name>⁺] [-active] [-inactive]  
+   [-dormant] [-help] 
+   
+

Privilege Required +

None +

Related Information +

fstrace apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf174.htm b/doc/html/AdminReference/auarf174.htm new file mode 100644 index 0000000..a021b34 --- /dev/null +++ b/doc/html/AdminReference/auarf174.htm @@ -0,0 +1,107 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace lslog

Purpose + + +

Displays information about a log +

Synopsis +

fstrace lslog [-set <set_name>⁺]  [-log <log_name>]  [-long]  [-help]
+   
+fstrace lsl [-s <set_name>⁺]  [-log <log_name>]  [-lon]  [-h] 
+

Description +

The fstrace lslog command reports whether the cmfx +log is available for use. If the -long argument is included, +the output reports the log's defined size, and whether that amount of +space is currently allocated in kernel memory or not. +

To change the cmfx trace log's size, use the fstrace +setlog command. To display or set whether space is allocated for +it in kernel memory, use the fstrace lsset or fstrace +setset command to display or set the state of the corresponding +cm event set, respectively. +

Options +

-set +: Names the event set for which to display information about the +corresponding trace log. The only acceptable value is cm +(for which the associated trace log is cmfx). Provide either +this argument or the -log argument, or omit both to display +information about the cmfx log by default. +
-log +: Names the trace log about which to report. The only acceptable +value is cmfx. Provide either this argument or the +-set argument, or omit both to report on the cmfx log by +default. +
-long +: Reports the defined size of the log in kilobyte units and whether that +amount of space is currently allocated in kernel memory. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

By default, the fstrace lslog command displays only the name of +the available log, cmfx, in the following format: +

   Available logs:
+   cmfx
+    
+

When the -long flag is included, the output also reports the +defined size of the log in kilobytes, and whether or not that amount of space +is currently allocated in kernel memory, in the following format: +

   Available logs:
+   cmfx : log_size kbytes (allocated  |  unallocated)
+   
+

The allocated state indicates that the indicated number of +kilobytes is reserved for the cmfx trace log in kernel +memory. The cm event set's state is either +active or inactive, as reported by the fstrace +lsset command, and set by the fstrace setset command's +-active or -inactive flags respectively. +

The unallocated state indicates that no kernel memory is +currently reserved for the cmfx trace log. The cm +event set's state is dormant, as reported by the fstrace +lsset command and set by the fstrace setset command's +-dormant flag. If the event set's state is later +changed to active or inactive, the number of kilobytes indicated as +log_size are again allocated in kernel memory. +

Examples +

The following example uses the -long flag to display information +about the cmfx log: +

   # fstrace lslog -log cmfx -long
+   Available logs:
+   cmfx : 60 kbytes (allocated)
+    
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fstrace setlog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf175.htm b/doc/html/AdminReference/auarf175.htm new file mode 100644 index 0000000..16fb554 --- /dev/null +++ b/doc/html/AdminReference/auarf175.htm @@ -0,0 +1,83 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace lsset

Purpose + + +

Reports the status of an event set +

Synopsis +

fstrace lsset [-set <set_name>⁺]  [-help] 
+   
+fstrace lss [-s <set_name>⁺]  [-h]
+

Description +

The fstrace lsset command displays a list of the available event +sets and reports their current status (active, inactive, or dormant). +

To change an event set's status, use the fstrace setset +command. +

Options +

-set +: Names the event set for which to display the status. The only +acceptable value is cm, which is also the default if this argument +is omitted. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output lists the available event sets and the status of each, in the +following format: +

   Available sets:
+   cm {active | inactive | dormant}
+   
+

where +

active +: Indicates that tracing is enabled for the event set, and kernel memory +allocated for the corresponding trace log. +
inactive +: Indicates that tracing is temporarily disabled for the event set, but +kernel memory still allocated for the corresponding trace log. +
dormant +: Indicates that tracing is disabled for the event set, and no kernel memory +allocated for the corresponding trace log. +

Examples +

The following example displays the available event set and its +status: +

   # fstrace lsset
+   Available sets:
+   cm active
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fstrace setset +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf176.htm b/doc/html/AdminReference/auarf176.htm new file mode 100644 index 0000000..30377e4 --- /dev/null +++ b/doc/html/AdminReference/auarf176.htm @@ -0,0 +1,75 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace setlog

Purpose + + +

Sets the size of a trace log +

Synopsis +

fstrace setlog [-log <log_name>⁺]  -buffersize <1-kilobyte_units>  [-help]
+      
+fstrace setl [-l <log_name>⁺]  -b <1-kilobyte_units>  [-h]
+      
+fstrace sl [-l <log_name>⁺]  -b <1-kilobyte_units>  [-h]
+

Description +

The fstrace setlog command defines the number of kilobytes of +kernel memory allocated for the cmfx trace log. If kernel +memory is currently allocated, the command clears the current log and creates +a new log buffer of the specified size. +

To display the current defined size of the log buffer, issue the +fstrace lslog command with the -long argument. To +control whether the indicated amount of space is actually allocated, use the +fstrace setset command to set the status of the cm event +set; to display the event set's status, use the fstrace +lsset command. +

Options +

-log +: Names trace log for which to set the size. The only acceptable +value is cmfx, which is also the default if this argument is +omitted. +
-buffersize +: Specifies the number of 1-kilobyte blocks of kernel memory to allocate for +the trace log. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command allocated 80 KB of kernel memory for the +cmfx trace log: +

   # fstrace setlog -log cmfx -buffersize 80
+    
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fstrace lslog +

fstrace setset +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf177.htm b/doc/html/AdminReference/auarf177.htm new file mode 100644 index 0000000..2d40e26 --- /dev/null +++ b/doc/html/AdminReference/auarf177.htm @@ -0,0 +1,75 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

fstrace setset

Purpose + + +

Sets the status of an event set +

Synopsis +

fstrace setset [-set <set_name>⁺]  [-active]  [-inactive]  [-dormant]  [-help] 
+   
+fs set [-s <set_name>⁺]  [-a]  [-i]  [-d]  [-h]
+

Description +

The fstrace setset command sets the status of the cm +kernel event set on the local machine, which determines whether trace messages +are recorded in the log buffer in kernel memory. +

Options +

-set +: Names the event set for which to set the status. The only +acceptable value cm, which is also the default if this argument is +omitted. +
-active +: Enables tracing for the event set and allocates kernel memory for the +associated trace log buffer. Provide one of this flag, the +-inactive flag, or the -dormant flag. +
-inactive +: Temporarily disables tracing for the event set, but does not change the +allocation of kernel memory for the associated trace log buffer. +Provide one of this flag, the -active flag, or the +-dormant flag. +
-dormant +: Disables tracing for the event set and frees the kernel memory previously +allocated for the associated trace log buffer. Provide one of this +flag, the -active flag, or the -inactive flag. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example sets the cm event set's status to +inactive: +

   # fstrace setset -set cm -inactive
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

fstrace setlog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf178.htm b/doc/html/AdminReference/auarf178.htm new file mode 100644 index 0000000..6537ddc --- /dev/null +++ b/doc/html/AdminReference/auarf178.htm @@ -0,0 +1,118 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

ftpd (AFS version)

+ + + + + +

Purpose +

Initializes the Internet File Transfer Protocol server +

Synopsis +

ftpd  [-d]  [-l]  [-t <timeout>]  [-v]  [-T <MaxTimeOut>]  [-u]  [-s]
+

Description +

The AFS-modified ftpd program functions like the standard UNIX +ftpd program, but also authenticates the issuer of the +ftp command (who is presumably working on a remote machine) with +the Authentication Server in the local cell (the home cell of the machine +where the ftpd process is running, as defined in the local +/usr/vice/etc/ThisCell file). The authentication is based on +the user name and password provided at the ftp> prompts on the +remote machine. The Cache Manager on the machine running the +ftpd process stores the newly created token, identifying it by +process authentication group (PAG) rather than by the user's UNIX +UID. +

The issuer of the ftp command can be working in a foreign cell, +as long as the user name and password provided are valid in the cell where the +ftpd process is running. If the user name under which the +ftp command is issued does not exist in the Authentication Database +for the cell where the ftpd process is running, or the issuer +provides the wrong password, then the ftpd process logs the user +into the local file system of the machine where the ftpd process is +running. The success of this local login depends on the user name +appearing in the local password file and on the user providing the correct +local password. In the case of a local login, AFS server processes +consider the issuer of the ftp command to be the user +anonymous. +

In the recommended configuration, the AFS version of the ftpd +process is substituted for the standard version (only one of the versions can +run at a time). The administrator then has two choices: +

Name the binary for the AFS version something like +ftpd.afs, leaving the standard version as the +ftpd process. Change the inetd.conf +configuration file to refer to the ftpd.afs file rather than +to the standard version. +
Rename the binary for the AFS version to the standard name (such as +ftpd) and rename the binary for the standard version to something +like ftpd.orig. No change to the +inetd.conf file is necessary, but it is not as obvious that +the standard version of the ftpd process is no longer in +use. +

Cautions +

The AFS distribution does not include an AFS-modified version of this +command for every system type. On system types that use an integrated +authentication system, it is appropriate instead to control the +ftpd daemon's handling of AFS authentication through the +integrated system. For example, on system types that use the Pluggable +Authentication Module (PAM), add an ftpd entry that references the +AFS PAM module to the PAM configuration file. For instructions on +incorporating AFS into a machine's integrated authentication system, see +the IBM AFS Quick Beginnings. +

Some system types impose the following requirement. If the issuer of +the ftp command on the remote machine is using a shell other than +/bin/csh, then the /etc/shells file on the local disk of +the machine being accessed (the machine running the ftpd process) +must include an entry for the alternate shell. +

Options +

-d +: Directs debugging information to the system log daemon. +
-l +: Directs each FTP session to be logged to the system log daemon. +
-t +: Specifies a timeout period. By default, the FTP server will timeout +an inactive session after 15 minutes. +
-v +: Same as -d. +
-T +: Specifies a timeout period in seconds. By default, the FTP server +will timeout after 2 hours (7200 seconds). +
-s +: Turns on socket level debugging. Do not use this flag. It is +valid only on an operating system level that AFS does not support. +
-u +: Specifies the default UNIX mode bit file mask to use. +

Privilege Required +

See the UNIX manual page for the ftpd process. +

Related Information +

UNIX manual page for ftp +

UNIX manual page for ftpd +

IBM AFS Quick Beginnings +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf179.htm b/doc/html/AdminReference/auarf179.htm new file mode 100644 index 0000000..1c0ee2e --- /dev/null +++ b/doc/html/AdminReference/auarf179.htm @@ -0,0 +1,150 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

inetd (AFS version)

+ + + + + +

Purpose +

Initializes the Internet service daemon +

Synopsis +

inetd [-d]  [<configfile>]
+

Description +

The AFS-modified inetd program functions like the standard UNIX +inetd program, but also enables users of the remote services it +supports to access them as authenticated AFS users, provided that the +supported services are also AFS-modified versions that pass AFS tokens +(authentication information). Examples of supported services are the +rcp and rsh programs. +

The AFS inetd program can service the standard UNIX versions of +the remote services, but it is instead recommended that the standard UNIX +version of the inetd program be run in parallel with the AFS +version. Name the AFS version something like +inetd.afs and use it to service requests from AFS-modified +programs; use the standard inetd program to service requests +from standard UNIX programs. This separation requires using two +different inetd.conf files, as described in the following +section. +

Cautions +

Several configuration changes are necessary for token passing to work +correctly with the AFS version of the inetd program. There +are possibly other UNIX-based requirements or restrictions not mentioned +here; consult the UNIX manual page. (One important restriction is +that there can be no blank lines in the configuration file other than at the +end.) +

The requirements and restrictions include the following. They assume +that the inetd.afs process is running in parallel with the +standard inetd process. +

For token passing to work, the request must come from the AFS version of +the remote service (such as the AFS rcp or AFS rsh +command). If the remote service is the standard UNIX version, it cannot +pass a token. The issuer of the remote command is authenticated only in +the local file system, not with AFS. +
The machine's initialization files (/etc/rc file or +equivalent) must invoke both the standard inetd and +inetd.afs programs. +
An AFS-specific inetd.conf file, perhaps called +inetd.conf.afs, must exist alongside the standard +one. When initializing the inetd.afs program, specify +this configuration file rather than the standard one. Each line in the +inetd.conf.afs file must include an additional field, +fifth from the left, to specify the identity under which the program is to +run. The normal choice is the local superuser root. +The following sample shows the only lines that need to appear in this +file: +
```
   ta-rauth stream tcp nowait root internal          ta-rauth
+   shell    stream tcp nowait root /usr/etc/rshd     rshd
+   login    stream tcp nowait root /usr/etc/rlogind  rlogind
+
```
+
Substitute appropriate values for the binary locations and names in the +instructions, particularly for the shell and login +processes. Include the login instruction only if the +AFS-modified versions of login utilities are also in use in the cell; +otherwise, refer to login in the standard +inetd.conf instead. +
Note also that some system types use different process names. For +example, on Sun system types change rshd to +in.rshd and rlogind.afs to +in.rlogind.afs in the shell and +login instructions, respectively. +
Edit the standard inetd.conf file (referenced by the +standard inetd process): comment out the shell +instruction and, if AFS-modified versions of login utilities are in use in the +cell, the login instruction. The +inetd.conf.afs file references these processes +instead. Retain the login instruction if AFS-modified +versions of login utilities are not being used. Alter the +ftp instruction to refer to the AFS version of the ftpd +process, if it is substituted for the standard version. Do not insert +the extra fifth column into instructions in the standard +inetd.conf file if it does not already appear there. +See the following Examples section for an illustration. +

Options +

See the UNIX manual page for the inetd program. +

Examples +

The following are sample inetd.conf.afs and +inetd.conf files, appropriate for use when the +inetd.afs program is running in parallel with the standard +inetd and AFS-modified login utilities are being used in the +cell. Changes to the standard inetd.conf file include +referencing the AFS version of the ftpd binary and commenting out +the shell and login lines. The example +inetd.conf file does not include the extra fifth +column. Do not use these examples without modifying them appropriately +for the local machine type or cell. +

   # AFS version of Internet server configuration database 
+   #(EXAMPLE ONLY)
+   #
+   ta-rauth stream tcp nowait root internal           ta-rauth
+   shell    stream tcp nowait root /usr/etc/rshd      rshd
+   login    stream tcp nowait root /usr/etc/rlogind   rlogind
+   
+   # Standard version of Internet server configuration database 
+   #(EXAMPLE ONLY)
+   #
+   ftp	  stream tcp nowait /etc/ftpd.afs   ftpd.afs
+   telnet stream tcp nowait /etc/telnetd    telnetd
+   #shell stream tcp nowait /etc/rshd       rshd
+   #login stream tcp nowait /etc/rlogind    rlogind
+   finger stream tcp nowait /usr/etc/fingd  fingd
+   uucp	  stream tcp nowait /etc/uucpd	    uucpd
+   exec	  stream tcp nowait /etc/rexecd	    rexecd
+   comsat dgram	 udp wait   /etc/comsat	    comsat
+   talk	  dgram	 udp wait   /etc/talkd	    talkd
+   ntalk  dgram	 udp wait   /usr/etc/ntalkd talkd
+   time	  dgram	 udp wait   /etc/miscd	    timed
+

Privilege Required +

See the UNIX manual page for the inetd program. +

Related Information +

rcp (AFS version) +

rsh (AFS version) +

UNIX manual page for inetd +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf180.htm b/doc/html/AdminReference/auarf180.htm new file mode 100644 index 0000000..206a5f3 --- /dev/null +++ b/doc/html/AdminReference/auarf180.htm @@ -0,0 +1,93 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kadb_check

+ + + +

Purpose +

Checks the integrity of the Authentication Database +

Synopsis +

kadb_check -database <kadb_file>  [-uheader]  [-kheader]  [-entries]  
+           [-verbose]  [-rebuild <out_file>]  [-help]
+   
+kadb_check -d <kadb_file>  [-u]  [-k]  [-e]  [-v]  [-r <out_file>]  [-h]
+

Description +

The kadb_check command checks the integrity of the Protection +Database, reporting any errors or corruption it finds. If there are +problems, do not issue any kas commands until the database is +repaired. +

Cautions +

The results can be unpredictable if the Authentication Server makes changes +to the Authentication Database while this command is running. Use the +bos shutdown command to shutdown the local kaserver +process before running this command, or before creating a second copy of the +kaserver.DB0 file (with a different name) on which to run +the command. +

Options +

-database +: Names the Authentication Database (copy of the +kaserver.DB0 file) to check. If the current working +directory is not the location of the file, provide a pathname, either full or +relative to the current working directory. +
-uheader +: Displays information which Ubik maintains in the database's +header. +
-kheader +: Displays information which the Authentication Server maintains in the +database's header. +
-entries +: Outputs every entry in the database, providing information similar to that +returned by the kas examine command. +
-verbose +: Reports additional information about the database, including the number of +free (allocated but unused) entries in the database. +
-rebuild +: Names the file in which to record a list of kas commands which, +if issued in the command shell, recreate the current state of the database +being verified. Partial pathnames are interpreted relative to the +current working directory. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

If there are errors in the database, the output always reports them on the +standard error stream. If any options other than -database +or -help are provided, the output written to the standard output +stream includes additional information as described for each option in the +preceding Options section of this reference page. The output +is intended for debugging purposes and is meaningful to someone familiar with +the internal structure of the Authentication Database. +

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

bos shutdown +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf181.htm b/doc/html/AdminReference/auarf181.htm new file mode 100644 index 0000000..f938088 --- /dev/null +++ b/doc/html/AdminReference/auarf181.htm @@ -0,0 +1,189 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas

+ + + + + +

Purpose +

Introduction to the kas command suite +

Description +

The commands in the kas command suite are the administrative +interface to the Authentication Server, which runs on each database server +machine in a cell, maintains the Authentication Database, and provides the +authentication tickets that client applications must present to AFS servers in +order to obtain access to AFS data and other services. +

There are several categories of commands in the kas command +suite: +

Commands to create, modify, examine and delete entries in the +Authentication Database, including passwords: kas create, +kas delete, kas examine, kas list, kas +setfields, kas setkey, kas setpassword, and +kas unlock +
Commands to create, delete, and examine tokens and server tickets: +kas forgetticket, kas listtickets, kas +noauthentication, and kas stringtokey +
A command to enter interactive mode: kas interactive +
A command to trace Authentication Server operations: kas +statistics +
Commands to obtain help: kas apropos and kas +help +

Because of the sensitivity of information in the Authentication Database, +the Authentication Server authenticates issuers of kas commands +directly, rather than accepting the standard token generated by the Ticket +Granting Service. Any kas command that requires +administrative privilege prompts the issuer for a password. The +resulting ticket is valid for six hours unless the maximum ticket lifetime for +the issuer or the Authentication Server's Ticket Granting Service is +shorter. + + +

To avoid having to provide a password repeatedly when issuing a sequence of +kas commands, enter interactive mode by issuing the +kas interactive command, typing kas without any +operation code, or typing kas followed by a user and cell name, +separated by an at-sign (@; an example is kas +smith.admin@abc.com). After prompting once for a +password, the Authentication Server accepts the resulting token for every +command issued during the interactive session. See the reference page +for the kas interactive command for a discussion of when to use +each method for entering interactive mode and of the effects of entering a +session. +

The Authentication Server maintains two databases on the local disk of the +machine where it runs: +

The Authentication Database (/usr/afs/db/kaserver.DB0) +stores the information used to provide AFS authentication services to users +and servers, including the password scrambled as an encryption key. The +reference page for the kas examine command describes the +information in a database entry. +
An auxiliary file (/usr/afs/local/kaauxdb by default) that +tracks how often the user has provided an incorrect password to the local +Authentication Server. The reference page for the kas +setfields command describes how the Authentication Server uses this file +to enforce the limit on consecutive authentication failures. To +designate an alternate directory for the file, use the kaserver +command's -localfiles argument. +

Options +

The following arguments and flags are available on many commands in the +kas suite. (Some of them are unavailable on commands entered +in interactive mode, because the information they specify is established when +entering interactive mode and cannot be changed except by leaving interactive +mode.) The reference page for each command also lists them, but they +are described here in greater detail. +

+ +-admin_username +

Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. If this argument is +omitted, the kas command interpreter requests authentication for +the identity under which the issuer is logged onto the local machine. +Do not combine this argument with the -noauth flag. + +

-cell <cell name> +

The value of the AFSCELL environment variable +
The local /usr/vice/etc/ThisCell file +

The -cell argument is not available on commands issued in +interactive mode. The cell defined when the kas command +interpreter enters interactive mode applies to all commands issued during the +interactive session. + +

-help +

+ +-noauth +

Establishes an unauthenticated connection to the Authentication Server, in +which the Authentication Server treats the issuer as the unprivileged user +anonymous. It is useful only when authorization checking is +disabled on the server machine (during the installation of a server machine or +when the bos setauth command has been used during other unusual +circumstances). In normal circumstances, the Authentication Server +allows only privileged users to issue most kas commands, and +refuses to perform such an action even if the -noauth flag is +provided. Do not combine this flag with the -admin_username +and -password_for_admin arguments. +

+ +-password_for_admin +

Specifies the password of the command's issuer. It is best to +omit this argument, which echoes the password visibly in the command shell, +instead enter the password at the prompt. Do not combine this argument +with the -noauth flag. +

+ +-servers +

Establishes a connection with the Authentication Server running on each +specified database server machine, instead of on each machine listed in the +local /usr/vice/etc/CellServDB file. In either case, the +kas command interpreter then chooses one of the machines at random +to contact for execution of each subsequent command. The issuer can +abbreviate the machine name to the shortest form that allows the local name +service to identify it uniquely. +

Privilege Required +

To issue most kas commands, the issuer must have the +ADMIN flag set in his or her Authentication Database entry (use the +kas setfields command to turn the flag on). +

Related Information +

kas noauthentication +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf182.htm b/doc/html/AdminReference/auarf182.htm new file mode 100644 index 0000000..e51a166 --- /dev/null +++ b/doc/html/AdminReference/auarf182.htm @@ -0,0 +1,71 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas apropos

+ + + +

Purpose +

Displays each help entry containing a keyword string +

Synopsis +

kas apropos -topic <help string>  [-help]
+    
+kas a  -t <help string>  [-h]
+

Description +

The kas apropos command displays the first line of the online +help entry for any kas command that has the string specified by the +-topic argument in its name or short description. +

To display the syntax for a command, use the kas 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 +kas command where the string specified with the -topic +argument is part of the command name or first line. +

Examples +

The following command lists all kas commands that include the +word key in their names or short descriptions: +

   % kas apropos key
+   setkey: set a user's key
+   stringtokey: convert a string to a key
+   
+

Privilege Required +

None, and no password is required. +

Related Information +

kas +

kas help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf183.htm b/doc/html/AdminReference/auarf183.htm new file mode 100644 index 0000000..8ba5b98 --- /dev/null +++ b/doc/html/AdminReference/auarf183.htm @@ -0,0 +1,117 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas create

+ + + + + +

Purpose +

Creates an entry in the Authentication Database +

Synopsis +

kas create -name <name of user>  [-initial_password <initial password>] 
+           [-admin_username <admin principal to use for authentication>] 
+           [-password_for_admin <admin password>]  [-cell <cell name>] 
+           [-servers <explicit list of authentication servers>⁺]  
+           [-noauth]  [-help]
+   
+kas c -na <name of user>  [-i <initial password>] 
+      [-a <admin principal to use for authentication>]  
+      [-p <admin password>]  [-c <cell name>]  
+      [-s <explicit list of authentication servers>⁺]  [-no]  [-h] 
+

Description +

The kas create command creates an entry in the Authentication +Database for the user named by the -name argument. +

To avoid having the account's initial password echo visibly at the +shell prompt, omit the -initial_password argument; the command +interpreter prompts for the password and does not echo it visibly. +Whether or not -initial_password is omitted, the Authentication +Server converts the password into a form suitable for use as an encryption +key, and records it in the entry's key field. +

To alter settings in an Authentication Database entry, use the kas +setfields command. To examine an entry, use the kas +examine command. To list every entry in the database, use the +kas list command. +

Options +

-name +: Names the new Authentication Database entry. Because it is the name +under which the user logs in, it must obey the restrictions that many +operating systems impose on user names (usually, to contain no more than eight +lowercase letters). +
-initial_password +: Sets the user's password; provide a character string that can +include uppercase and lowercase letters, numerals and punctuation. The +Authentication Server scrambles the string into an octal string suitable for +use as an encryption key before placing it in the entry's key +field. If this argument is omitted, the command interpreter prompts for +the string and does not echo it visibly. +
-admin_username +: Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +
-password_for_admin +: Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory kas reference page. +
-servers +: Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example shows the prompts that appear when an administrator +logged in as admin creates an Authentication Database entry for the +user smith, and does not include either the +-initial_password or -password_for_admin +arguments. +

   % kas create smith
+   Password for admin: 
+   initial_password:
+   Verifying, please re-enter initial_password:
+   
+

Privilege Required +

The issuer must have the ADMIN flag set on his or her +Authentication Database entry. +

Related Information +

kas +

kas list +

kas setfields +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf184.htm b/doc/html/AdminReference/auarf184.htm new file mode 100644 index 0000000..c7aba97 --- /dev/null +++ b/doc/html/AdminReference/auarf184.htm @@ -0,0 +1,98 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas delete

+ + + + +

Purpose +

Deletes an entry from the Authentication Database +

Synopsis +

kas delete -name <name of user>  
+           [-admin_username <admin principal to use for authentication>]  
+           [-password_for_admin <admin password>]  [-cell <cell name>]  
+           [-servers <explicit list of authentication servers>⁺]  
+           [-noauth]  [-help] 
+   
+kas d -na <name of user>  [-a <admin principal to use for authentication>] 
+      [-p <admin password>]  [-c <cell name>]  
+      [-s <explicit list of authentication servers>⁺]  [-no]  [-h] 
+     
+kas rm -na <name of user>  [-a <admin principal to use for authentication>]  
+       [-p <admin password>]  [-c <cell name>]  
+       [-s <explicit list of authentication servers>⁺]  [-no]  [-h]  
+

Description +

The kas delete command removes from the Authentication Database +the user entry named by the -name argument. The indicated +user becomes unable to log in, or the indicated server becomes unreachable +(because the Authentication Server's Ticket Granting Service module no +longer has a key with which to seal tickets for the server). +

Options +

-name +: Names the Authentication Database entry to delete. +
-admin_username +: Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +
-password_for_admin +: Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory kas reference page. +
-servers +: Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example shows the administrative user admin +entering interactive mode to delete three accounts. +

   % kas
+   Password for admin:
+   ka> delete smith
+   ka> delete pat
+   ka> delete terry
+   
+

Privilege Required +

The issuer must have the ADMIN flag set on his or her +Authentication Database entry. +

Related Information +

kas +

kas create +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf185.htm b/doc/html/AdminReference/auarf185.htm new file mode 100644 index 0000000..05775b8 --- /dev/null +++ b/doc/html/AdminReference/auarf185.htm @@ -0,0 +1,261 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas examine

+ + + + + + + + + + + + + + + + + + + +

Purpose +

Displays information from an Authentication Database entry +

Synopsis +

kas examine -name <name of user> [-showkey] 
+            [-admin_username <admin principal to use for authentication>]  
+            [-password_for_admin <admin password>]  [-cell <cell name>] 
+            [-servers <explicit list of authentication servers>⁺]  
+            [-noauth]  [-help] 
+    
+kas e -na <name of user>  [-sh] 
+      [-a <admin principal to use for authentication>] 
+      [-p <admin password>]  [-c <cell name>] 
+      [-se <explicit list of authentication servers>⁺]  [-no]  [-h]  
+

Description +

The kas examine command formats and displays information from +the Authentication Database entry of the user named by the -name +argument. +

To alter the settings displayed with this command, issue the kas +setfields command. +

Cautions +

Displaying actual keys on the standard output stream by including the +-showkey flag constitutes a security exposure. For most +purposes, it is sufficient to display a checksum. +

Options +

-name +: Names the Authentication Database entry from which to display +information. +
-showkey +: Displays the octal digits that constitute the key. The issuer must +have the ADMIN flag on his or her Authentication Database +entry. +
-admin_username +: Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +
-password_for_admin +: Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory kas reference page. +
-servers +: Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output includes: +

The entry name, following the string User data for. +
One or more status flags in parentheses; they appear only if an +administrator has used the kas setfields command to change them +from their default values. A plus sign (+) separates the +flags if there is more than one. The nondefault values that can appear, +and their meanings, are as follows: +
+
ADMIN +
Enables the user to issue privileged kas commands (default is +NOADMIN) +
NOTGS +
Prevents the user from obtaining tickets from the Authentication +Server's Ticket Granting Service (default is TGS) +
NOSEAL +
Prevents the Ticket Granting Service from using the entry's key field +as an encryption key (default is SEAL) +
NOCPW +
Prevents the user from changing his or her password (default is +CPW) +
+ + + +
The key version number, in parentheses, following the word key, +then one of the following. +
- A checksum equivalent of the key, following the string cksum +is, if the -showkey flag is not included. The checksum +is a decimal number derived by encrypting a constant with the key. In +the case of the afs entry, this number must match the +checksum with the corresponding key version number in the output of the +bos listkeys command; if not, follow the instructions in the +IBM AFS Administration Guide for creating a new server encryption +key. +
- The actual key, following a colon, if the -showkey flag is +included. The key consists of eight octal numbers, each represented as +a backslash followed by three decimal digits. +
+
The date the user last changed his or her own password, following the +string last cpw (which stands for "last change of +password"). +
The string password will never expire indicates that the +associated password never expires; the string password will +expire is followed by the password's expiration date. After +the indicated date, the user cannot authenticate, but has 30 days after it in +which to use the kpasswd or kas setpassword command to +set a new password. After 30 days, only an administrator (one whose +account is marked with the ADMIN flag) can change the password by +using the kas setpassword command. To set the password +expiration date, use the kas setfields command's +-pwexpires argument. +
The number of times the user can fail to provide the correct password +before the account locks, followed by the string consecutive unsuccessful +authentications are permitted, or the string An unlimited number of +unsuccessful authentications is permitted to indicate that there is no +limit. To set the limit, use the kas setfields +command's -attempts argument. To unlock a locked +account, use the kas unlock command. The kas +setfields reference page discusses how the implementation of the lockout +feature interacts with this setting. +
The number of minutes for which the Authentication Server refuses the +user's login attempts after the limit on consecutive unsuccessful +authentication attempts is exceeded, following the string The lock time +for this user is. Use the kas command's +-locktime argument to set the lockout time. This line +appears only if a limit on the number of unsuccessful authentication attempts +has been set with the the kas setfields command's +-attempts argument. +
An indication of whether the Authentication Server is currently refusing +the user's login attempts. The string User is not +locked indicates that authentication can succeed, whereas the string +User is locked until time indicates that the user cannot +authenticate until the indicated time. Use the kas unlock +command to enable a user to attempt authentication. This line appears +only if a limit on the number of unsuccessful authentication attempts has been +set with the kas setfields command's -attempts +argument. +
The date on which the Authentication Server entry expires, or the string +entry never expires to indicate that the entry does not +expire. A user becomes unable to authenticate when his or her entry +expires. Use the kas setfields command's +-expiration argument to set the expiration date. +
The maximum possible lifetime of the tokens that the Authentication Server +grants the user. This value interacts with several others to determine +the actual lifetime of the token, as described on the klog +reference page. Use the kas setfields command's +-lifetime argument to set this value. +
The date on which the entry was last modified, following the string +last mod on and the user name of the administrator who modified +it. The date on which a user changed his or her own password is +recorded on the second line of output as last cpw instead. +
An indication of whether the user can reuse one of his or her last twenty +passwords when issuing the kpasswd, kas setpassword, or +kas setkey commands. Use the kas setfields +command's -reuse argument to set this restriction. +

Examples +

The following example command shows the user smith displaying +her own Authentication Database entry. Note the ADMIN flag, +which shows that smith is privileged. +

   % kas examine smith
+   Password for smith:
+   User data for smith (ADMIN)
+    key (0) cksum is 3414844392,  last cpw: Thu Mar 25 16:05:44 1999
+    password will expire:  Fri Apr 30 20:44:36 1999
+    5 consecutive unsuccessful authentications are permitted.
+    The lock time for this user is 25.5 minutes.
+    User is not locked.
+    entry never expires. Max ticket lifetime 100.00 hours.
+    last mod on Tue Jan 5 08:22:29 1999 by admin
+    permit password reuse
+   
+

In the following example, the user pat examines his +Authentication Database entry to determine when the account lockout currently +in effect will end. +

   % kas examine pat
+   Password for pat:
+   User data for pat
+    key (0) cksum is 73829292912,  last cpw: Wed Apr 7 11:23:01 1999
+    password will expire:  Fri  Jun 11 11:23:01 1999
+    5 consecutive unsuccessful authentications are permitted.
+    The lock time for this user is 25.5 minutes.
+    User is locked until Tue Sep 21 12:25:07 1999
+    entry expires on never. Max ticket lifetime 100.00 hours.
+    last mod on Thu Feb 4 08:22:29 1999 by admin
+    permit password reuse
+   
+

In the following example, an administrator logged in as admin +uses the -showkey flag to display the octal digits that constitute +the key in the afs entry. +

   % kas examine -name afs -showkey
+   Password for admin: admin_password
+   User data for afs
+    key (12): \357\253\304\352\234\236\253\352, last cpw: no date 
+    entry never expires. Max ticket lifetime 100.00 hours.
+    last mod on Thu Mar 25 14:53:29 1999 by admin
+    permit password reuse
+   
+

Privilege Required +

A user can examine his or her own entry. To examine others' +entries or to include the -showkey flag, the issuer must have the +ADMIN flag set in his or her Authentication Database entry. +

Related Information +

kas +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf186.htm b/doc/html/AdminReference/auarf186.htm new file mode 100644 index 0000000..bdd8c98 --- /dev/null +++ b/doc/html/AdminReference/auarf186.htm @@ -0,0 +1,64 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas forgetticket

+ + + + + +

Purpose +

Discards all tickets for the issuer +

Synopsis +

kas forgetticket [-all]  [-help]
+    
+kas f [-a]  [-h]
+

Description +

The kas forgetticket command discards all of the issuer's +tickets stored in the local machine's kernel memory. This includes +the AFS server ticket from each cell in which the user has authenticated, and +any tickets that the user have acquired during the current kas +session (either when entering the session or by using the kas +getticket command). +

Options +

-all +: Discards all tickets. This argument explicitly invokes the +command's default behavior. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command discards all of the issuer's tickets. +

   % kas forgetticket
+   
+

Privilege Required +

None, and no password is required. +

Related Information +

kas +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf187.htm b/doc/html/AdminReference/auarf187.htm new file mode 100644 index 0000000..e29d23b --- /dev/null +++ b/doc/html/AdminReference/auarf187.htm @@ -0,0 +1,88 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas help

+ + + +

Purpose +

Displays the syntax of each specified kas command or lists +functional descriptions of all kas commands +

Synopsis +

kas help [-topic <help string>⁺]  [-help]
+   
+kas h [-t <help string>⁺]  [-h]
+

Description +

The kas help command displays the complete online help entry +(short description and syntax statement) for each command operation code +specified by the -topic argument. If the -topic +argument is omitted, the output includes the first line (name and short +description) of the online help entry for every kas command. +

To list every kas command whose name or short description +includes a specified keyword, use the kas apropos command. +

Options +

-topic +: Indicates each command for which to display the complete online help +entry. Omit the kas part of the command name, providing only +the operation code (for example, specify setpassword, not kas +setpassword). If this argument is omitted, the output briefly +describes every kas command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each kas command consists of the +following two or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following command displays the online help entry for the kas +setpassword command: +

   % kas help setpassword
+   kas setpassword: set a user's password 
+   aliases: sp 
+   Usage: kas setpassword -name <name of user> 
+   [-new_password <new password>] [-kvno <key version number>] 
+   [-admin_username <admin principal to use for authentication>] 
+   [-password_for_admin <password>] [-cell <cell name>] 
+   [-servers <explicit list of authentication servers>+] [-help]  
+   
+

Privilege Required +

None, and no password is required. +

Related Information +

kas +

kas apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf188.htm b/doc/html/AdminReference/auarf188.htm new file mode 100644 index 0000000..3529c24 --- /dev/null +++ b/doc/html/AdminReference/auarf188.htm @@ -0,0 +1,133 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas interactive

Purpose +

Enters interactive mode +

Synopsis +

kas interactive [-admin_username <admin principal to use for authentication>] 
+                [-password_for_admin <admin password>]  [-cell <cell name>] 
+                [-servers <explicit list of authentication servers>⁺]  
+                [-noauth]  [-help]
+      
+kas i [-a <admin principal to use for authentication>]  
+      [-p <admin password>]  [-c <cell name>]  
+      [-s <explicit list of authentication servers>⁺]  [-n]  [-h]
+

Description +

The kas interactive command establishes an interactive session +for the issuer of the command. By default, the command interpreter +establishes an authenticated connection for the user logged into the local +file system with all of the Authentication Servers listed in the local +/usr/vice/etc/CellServDB file for the cell named in the local +/usr/vice/etc/ThisCell file. To specify an alternate +identity, cell name, or list of Authentication Servers, include the +-admin_username, -cell, or -servers arguments +respectively. Interactive mode lasts for six hours unless the maximum +ticket lifetime for the issuer or the Authentication Server's Ticket +Granting Service is shorter. +

There are two other ways to enter interactive mode, in addition to the +kas interactive command: +

Type the kas command at the shell prompt without any operation +code. If appropriate, include one or more of the +-admin_username, -password_for_admin, -cell, +and -servers arguments. +
Type the kas command followed by a user name and cell name, +separated by an @ sign (for example: kas +admin@abc.com), to establish a connection under the specified +identity with the Authentication Servers listed in the local +/usr/vice/etc/CellServDB file for the indicated cell. If +appropriate, provide the -servers argument to specify an alternate +list of Authentication Server machines that belong to the indicated +cell. +

There are several consequences of entering interactive mode: +

The ka> prompt replaces the system (shell) prompt. When +typing commands at this prompt, provide only the operation code (omit the +command suite name, kas). +
The command interpreter does not prompt for the issuer's +password. +
The issuer's identity and password, the relevant cell, and the set of +Authentication Server machines specified when entering interactive mode apply +to all commands issued during the session. They cannot be changed +without leaving the session, except by using the (kas) +noauthentication command to replace the current authenticated +connections with unauthenticated ones. The -admin_username, +-password_for_admin, -cell, and -servers +arguments are ignored if provided on a command issued during interactive +mode. +

To establish an unauthenticated connection to the Authentication Server, +include the -noauth flag or provide an incorrect password. +Unless authorization checking is disabled on each Authentication Server +machine involved, however, it is not possible to perform any privileged +operations within such a session. +

To end the current authenticated connection and establish an +unauthenticated one, issue the (kas) noauthentication +command. To leave interactive mode and return to the regular shell +prompt, issue the (kas) quit command. +

Options +

-admin_username +: Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +
-password_for_admin +: Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory kas reference page. +
-servers +: Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example shows a user entering interactive mode as the +privileged user admin. +

   % kas interactive admin
+   Password for admin: admin_password
+   ka>
+   
+

Privilege Required +

None +

Related Information +

kas +

kas noauthentication +

kas quit +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf189.htm b/doc/html/AdminReference/auarf189.htm new file mode 100644 index 0000000..bcfffaf --- /dev/null +++ b/doc/html/AdminReference/auarf189.htm @@ -0,0 +1,118 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas list

+ + + + +

Purpose +

Displays all entries in the Authentication Database +

Synopsis +

kas list [-long]  [-showadmin]  [-showkey]
+         [-admin_username <admin principal to use for authentication>] 
+         [-password_for_admin <admin password>]  [-cell <cell name>] 
+         [-servers <explicit list of authentication servers>⁺]
+         [-noauth]  [-help]
+   
+kas ls [-l]  [-showa]   [-showk]
+       [-a <admin principal to use for authentication>] 
+       [-p <admin password>]  [-c <cell name>] 
+       [-se <explicit list of authentication servers>⁺]  [-n]  [-h] 
+

Description +

The kas list command either displays all entries from the +Authentication Database by name, or displays the full database entry for a +defined set of entries, as determined by the flag provided: +

To display every entry in the Authentication Database in full, include the +-long flag. +
To display only those entries in full that have the ADMIN flag +set, include the -showadmin flag. +
To list only the name of each Authentication Database entry, omit both the +-long and -showadmin flags. +

By default, full entries include a checksum for the encryption key, rather +than the actual octal digits that constitute the key. To display the +octal digits, include the -showkey flag with the -long +or -showadmin flag. +

Options +

-long +: Displays every Authentication Database entry in full. Provide this +flag or the -showadmin flag, or omit both to display just the name +of every database entry. +
-showadmin +: Displays in full only the Authentication Database entries that have the +ADMIN flag set. Provide this flag or the -long +flag, or omit both to display just the name of every database entry. +
-showkey +: Displays the octal digits that constitute the key in each full +entry. Provide either the -long or -showadmin +flag along with this one. +
-admin_username +: Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +
-password_for_admin +: Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory kas reference page. +
-servers +: Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

If neither the -long or -showadmin flag is provided, +the output lists the name of each entry in the Authentication Database on its +own line. +

If the -long flag is included, the output includes every +Authentication Database entry in full. If the -showadmin +flag is included, the output includes in full only the Authentication Database +entries that have the ADMIN flag set. If the +-showkey is provided along with either one, the output includes the +octal digits that constitute the encryption key in each entry. +

A full Authentication Database entry includes the same information +displayed by the kas examine command; for details, see that +command's reference page. +

Privilege Required +

The issuer must have the ADMIN flag set on his or her +Authentication Database entry. +

Related Information +

kas +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf190.htm b/doc/html/AdminReference/auarf190.htm new file mode 100644 index 0000000..4ecb725 --- /dev/null +++ b/doc/html/AdminReference/auarf190.htm @@ -0,0 +1,102 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas listtickets

+ + + + +

Purpose +

Displays all of the issuer's tickets (tokens) +

Synopsis +

kas listtickets [-name <name of server>]  [-long]  [-help]
+   
+kas listt [-n <name of server>]  [-l]  [-h]
+

Description +

The kas listtickets command displays the associated user ID (AFS +UID), cell name, and expiration date of some or all of the issuer's +tickets (tokens), depending on which options are provided: +

To display all tokens, provide neither the -name argument nor +-long flag. The output is similar to that of the +tokens command. +
To display a single token, provide the -name argument to +specify name of the Authentication Database entry for the entity that accepts +the token. All AFS server processes accept tokens sealed with the key +from the afs entry. +
To display in addition the octal numbers that constitute the token and +session key, provide the -long flag. +

Options +

-name +: Names the Authentication Database entry of the entity (usually a server +process) that accepts the token to display. +
-long +: Displays the octal numbers that constitute the session key and +ticket. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output reports the AFS UID of the user who owns the token, the service +(usually, afs) and cell for which it is valid, and its expiration +date, using the following format. If the message does not specify a +cell, the ticket is for the local cell. +

   User's (AFS ID AFS UID) tokens for service[@cellname] [Expires date]
+   
+

If the -long flag is provided, the output also includes the +octal numbers making up the session key and token, along with the key version +number and the number of bytes in the token (if the number of bytes is not 56, +there is an error). +

If the marker [>> POSTDATED <] appears instead of an +expiration date, the ticket does not become valid until the indicated +time. (Only internal calls can create a postdated ticket; there is +no standard interface that allows users to do this.) +

Examples +

The following two examples are for a user with AFS UID 1020 in the +abc.com cell and AFS UID 35 in the +test.abc.com cell. He is working on a machine +in the first cell and is authenticated in both cells. +

   % kas listtickets
+   User's (AFS ID 1020) tokens for afs [Expires Wed Mar 31 9:30:54 1999]
+   User's (AFS ID 35@test.abc.com) tokens for afs@test.abc.com  \
+             [Expires Wed Mar 31 13:54:26 1999]
+   
+   % kas listtickets -name afs -long
+   User's (AFS ID 1020) tokens for afs [Expires Wed Mar 31 9:30:54 1999]
+   SessionKey: \375\205\351\227\032\310\263\013
+   Ticket: (kvno = 0, len = 56): \033\005\221\156\203\278\312\058\016\133 (etc.)
+   
+

Privilege Required +

None, and no password is required. +

Related Information +

kas +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf191.htm b/doc/html/AdminReference/auarf191.htm new file mode 100644 index 0000000..680f223 --- /dev/null +++ b/doc/html/AdminReference/auarf191.htm @@ -0,0 +1,71 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas noauthentication

+ + + + + +

Purpose +

Discards an authenticated identity in interactive mode +

Synopsis +

noauthentication  [-help]
+   
+n  [-h]
+

Description +

The kas noauthentication command closes the (presumably +authenticated) connection that the issuer established with one or more +Authentication Server processes when entering interactive mode. It +opens a new unauthenticated connection to each server, assigning the issuer +the unprivileged identity anonymous. It does not actually +discard the user's tokens from the Cache Manager's memory (as the +unlog or kas forgetticket command does). Unless +authorization checking is disabled on each Authentication Server machine, it +becomes impossible to perform any privileged operations within the session +established by this command. +

This command is operative only during interactive mode, so omit the +kas command suite name from the command line. +

Options +

-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example command discards the authentication information with +which the user entered interactive mode. +

   ka> noauthentication
+   
+

Privilege Required +

None, and no password is required. +

Related Information +

kas +

kas forgetticket +

kas interactive +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf192.htm b/doc/html/AdminReference/auarf192.htm new file mode 100644 index 0000000..cec4626 --- /dev/null +++ b/doc/html/AdminReference/auarf192.htm @@ -0,0 +1,63 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas quit

+ + + + + +

Purpose +

Leaves interactive mode +

Synopsis +

quit  [-help]
+   
+q  [-h]
+

Description +

The kas quit command ends interactive mode, severing the +authenticated connection to one or more Authentication Server processes and +returning the issuer to the normal shell prompt. +

This command is operative only during interactive mode, so omit the +kas command suite name from the command line. +

Options +

-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example demonstrates how the normal command shell prompt +returns when the issuer leaves interactive mode. +

   ka> quit
+   %
+   
+

Privilege Required +

None, and no password is required. +

Related Information +

kas +

kas interactive +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf193.htm b/doc/html/AdminReference/auarf193.htm new file mode 100644 index 0000000..6a2f4cb --- /dev/null +++ b/doc/html/AdminReference/auarf193.htm @@ -0,0 +1,351 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas setfields

+ + + + + + + + + + + + + +

Purpose +

Sets optional characteristics in an Authentication Database entry +

Synopsis +

kas setfields -name <name of user>
+              [-flags <hex flag value or flag name expression>] 
+              [-expiration <date of account expiration>] 
+              [-lifetime <maximum ticket lifetime>] 
+              [-pwexpires <number days password is valid ([0..254])>]
+              [-reuse <permit password reuse (yes/no)>]
+              [-attempts <maximum successive failed login tries ([0..254])>]
+              [-locktime <failure penalty [hh:mm or minutes]>]
+              [-admin_username <admin principal to use for authentication>] 
+              [-password_for_admin <admin password>]  [-cell <cell name>] 
+              [-servers <explicit list of authentication servers>⁺]
+              [-noauth]  [-help]
+   
+kas setf -na <name of user>  [-f <hex flag value or flag name expression>]
+         [-e <date of account expiration>]  [-li <maximum ticket lifetime>]
+         [-pw <number days password is valid ([0..254])>]
+         [-r <permit password reuse (yes/no)>]
+         [-at <maximum successive failed login tries ([0..254])>]
+         [-lo <failure penalty [hh:mm or minutes]>]
+         [-ad <admin principal to use for authentication>] 
+         [-pa <admin password>]  [-c <cell name>]
+         [-s <explicit list of authentication servers>⁺]  [-no]  [-h] 
+   
+kas sf -na <name of user>  [-f <hex flag value or flag name expression>]
+       [-e <date of account expiration>]  [-li <maximum ticket lifetime>]
+       [-pw <number days password is valid ([0..254])>]
+       [-r <permit password reuse (yes/no)>]
+       [-at <maximum successive failed login tries ([0..254])>]
+       [-lo <failure penalty [hh:mm or minutes]>]
+       [-ad <admin principal to use for authentication>] 
+       [-pa <admin password>]  [-c <cell name>]
+       [-s <explicit list of authentication servers>⁺]  [-no]  [-h]
+

Description +

The kas setfields command changes the Authentication Database +entry for the user named by the -name argument in the manner +specified by the various optional arguments, which can occur singly or in +combination: +

To set the flags that determine whether the user has administrative +privileges to the Authentication Server, can obtain a ticket, can change his +or her password, and so on, include the -flags argument. +
To set when the Authentication Database entry expires, include the +-expiration argument. +
To set the maximum ticket lifetime associated with the entry, include the +-lifetime argument. The reference page for the +klog command explains how this value interacts with others to +determine the actual lifetime of a token. +
To set when the user's password expires, include the +-pwexpires argument. +
To set whether the user can reuse any of the previous twenty passwords +when creating a new one, include the -reuse argument. +
To set the maximum number of times the user can provide an incorrect +password before the Authentication Server refuses to accept any more attempts +(locks the issuer out), include the -attempts argument. +After the sixth failed authentication attempt, the Authentication Server logs +a message in the UNIX system log file (the syslog file or +equivalent, for which the standard location varies depending on the operating +system). +
To set how long the Authentication Server refuses to process +authentication attempts for a locked-out user, set the -locktime +argument. +

The kas examine command displays the settings made with this +command. +

Cautions +

The password lifetime set with the -pwexpires argument begins at +the time the user's password was last changed, rather than when this +command is issued. It can therefore be retroactive. If, for +example, a user changed her password 100 days ago and the password lifetime is +set to 100 days or less, the password effectively expires immediately. +To avoid retroactive expiration, instruct the user to change the password just +before setting a password lifetime. +

Administrators whose authentication accounts have the ADMIN flag +enjoy complete access to the sensitive information in the Authentication +Database. To prevent access by unauthorized users, use the +-attempts argument to impose a fairly strict limit on the number of +times that a user obtaining administrative tokens can provide an incorrect +password. Note, however, that there must be more than one account in +the cell with the ADMIN flag. The kas unlock +command requires the ADMIN privilege, so it is important that the +locked-out administrator (or a colleague) can access another +ADMIN-privileged account to unlock the current account. +

In certain circumstances, the mechanism used to enforce the number of +failed authentication attempts can cause a lockout even though the number of +failed attempts is less than the limit set by the -attempts +argument. Client-side authentication programs such as klog +and an AFS-modified login utility normally choose an Authentication Server at +random for each authentication attempt, and in case of a failure are likely to +choose a different Authentication Server for the next attempt. The +Authentication Servers running on the various database server machines do not +communicate with each other about how many times a user has failed to provide +the correct password to them. Instead, each Authentication Server +maintains its own separate copy of the auxiliary database file +kaserverauxdb (located in the /usr/afs/local directory +by default), which records the number of consecutive authentication failures +for each user account and the time of the most recent failure. This +implementation means that on average each Authentication Server knows about +only a fraction of the total number of failed attempts. The only way to +avoid allowing more than the number of attempts set by the +-attempts argument is to have each Authentication Server allow only +some fraction of the total. More specifically, if the limit on failed +attempts is f, and the number of Authentication Servers is +S, then each Authentication Server can only permit a number of +attempts equal to f divided by S (the Ubik +synchronization site for the Authentication Server tracks any remainder, +fmodS). +

Normally, this implementation does not reduce the number of allowed +attempts to less than the configured limit (f). If one +Authentication Server refuses an attempt, the client contacts another instance +of the server, continuing until either it successfully authenticates or has +contacted all of the servers. However, if one or more of the +Authentication Server processes is unavailable, the limit is effectively +reduced by a percentage equal to the quantity U divided by +S, where U is the number of unavailable servers and +S is the number normally available. +

To avoid the undesirable consequences of setting a limit on failed +authentication attempts, note the following recommendations: +

Do not set the -attempts argument (the limit on failed +authentication attempts) too low. A limit of nine failed attempts is +recommended for regular user accounts, to allow three failed attempts per +Authentication Server in a cell with three database server machines. +
Set fairly short lockout times when including the -locktime +argument. Although guessing passwords is a common method of attack, it +is not a very sophisticated one. Setting a lockout time can help +discourage attackers, but excessively long times are likely to be more of a +burden to authorized users than to potential attackers. A lockout time +of 25 minutes is recommended for regular user accounts. +
Do not assign an infinite lockout time on an account (by setting the +-locktime argument to 0 [zero]) unless there is a highly +compelling reason. Such accounts almost inevitably become locked at +some point, because each Authentication Server never resets the account's +failure counter in its copy of the kaauxdb file (in contrast, when +the lockout time is not infinite, the counter resets after the specified +amount of time has passed since the last failed attempt to that Authentication +Server). Furthermore, the only way to unlock an account with an +infinite lockout time is for an administrator to issue the kas +unlock command. It is especially dangerous to set an infinite +lockout time on an administrative account; if all administrative accounts +become locked, the only way to unlock them is to shut down all instances of +the Authentication Server and remove the kaauxdb file on +each. +

Options +

-name +

Names the Authentication Database account for which to change +settings. +

-flags +

Sets one or more of four toggling flags, adding them to any flags +currently set. Either specify one or more of the following strings, or +specify a hexidecimal number that combines the indicated values. To +return all four flags to their defaults, provide a value of 0 +(zero). To set more than one flag at once using the strings, connect +them with plus signs (example: NOTGS+ADMIN+CPW). To +remove all the current flag settings before setting new ones, precede the list +with an equal sign (example: =NOTGS+ADMIN+CPW). +

ADMIN +: The user is allowed to issue privileged kas commands +(hexadecimal equivalent is 0x004, default is +NOADMIN). + +
NOTGS +: The Authentication Server's Ticket Granting Service (TGS) refuses to +issue tickets to the user (hexadecimal equivalent is 0x008, default +is TGS). + +
NOSEAL +: The Ticket Granting Service cannot use the contents of this entry's +key field as an encryption key (hexadecimal equivalent is 0x020, +default is SEAL). + +
NOCPW +: The user cannot change his or her own password or key (hexadecimal +equivalent is 0x040, default is CPW). + +

-expiration +

Determines when the entry itself expires. When a user entry +expires, the user becomes unable to log in; when a server entry such as +afs expires, all server processes that use the associated key +become inaccessible. Provide one of the three acceptable values: +

never +: The account never expires (the default). +
mm/dd/yyyy +: Sets the expiration date to 12:00 a.m. on the +indicated date (month/day/year). Examples: 01/23/1999, +10/07/2000. +
"mm/dd/yyyy hh:MM" +: Sets the expiration date to the indicated time (hours:minutes) on +the indicated date (month/day/year). Specify the time in 24-hour format +(for example, 20:30 is 8:30 p.m.) Date +format is the same as for a date alone. Surround the entire instance +with quotes because it contains a space. Examples: +"01/23/1999 22:30", "10/07/2000 +3:45". +

Acceptable values for the year range from 1970 (1 January 1970 +is time 0 in the standard UNIX date representation) through 2037 +(2037 is the maximum because the UNIX representation cannot accommodate dates +later than a value in February 2038). +

-lifetime +

Specifies the maximum lifetime that the Authentication Server's +Ticket Granting Service (TGS) can assign to a ticket. If the account +belongs to a user, this value is the maximum lifetime of a token issued to the +user. If the account corresponds to a server such as afs, +this value is the maximum lifetime of a ticket that the TGS issues to clients +for presentation to the server during mutual authentication. +

Specify an integer that represents a number of seconds (3600 +equals one hour), or include a colon in the number to indicate a number of +hours and minutes (10:00 equals 10 hours). If this +argument is omitted, the default setting is 100:00 hours (360000 +seconds). +

-pwexpires +

Sets the number of days after the user's password was last 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 expires, the user is unable to authenticate, but has 30 +days after the expiration date in which to use the kpasswd command +to change the password (after that, only an administrator can change it by +using the kas setpassword command). Note that the clock +starts at the time the password was last changed, not when the kas +setfields command is issued. To avoid retroactive expiration, +have the user change the password just before issuing a command that includes +this argument. +

-reuse +

Specifies whether or not the user can reuse any of his or her last 20 +passwords. The acceptable values are yes to allow reuse of +old passwords (the default) and no to prohibit reuse of a password +that is similar to one of the previous 20 passwords. +

-attempts +

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 attempts (locks the user out) for the +amount of time specified by the -locktime argument. Provide +an integer from the range 1 through 254 to specify the +number of failures allowed, or 0 to indicate that there is no limit +on authentication attempts (the default value). +

-locktime +

Specifies how long the Authentication Server refuses authentication +attempts from a user who has exceeded the failure limit set by the +-attempts argument. +

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 kas command +interpreter 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 issue the kas unlock +command to unlock the account. +

-admin_username +

Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +

-password_for_admin +

Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +

-cell +

Names the cell in which to run the command. For more details, see +the introductory kas reference page. +

-servers +

Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

In the following example, an administrator using the admin +account grants administrative privilege to the user smith, and sets +the Authentication Database entry to expire at midnight on 31 December +2000. +

   % kas setfields -name smith -flags ADMIN -expiration 12/31/2000
+   Password for admin:
+   
+

In the following example, an administrator using the admin +account sets the user pat's password to expire in 60 days from +when it last changed, and prohibits reuse of passwords. +

   % kas setfields -name pat -pwexpires 60 -reuse no
+   Password for admin:
+   
+

Privilege Required +

The issuer must have the ADMIN flag set on his or her +Authentication Database entry. +

Related Information +

kas +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf194.htm b/doc/html/AdminReference/auarf194.htm new file mode 100644 index 0000000..2265aba --- /dev/null +++ b/doc/html/AdminReference/auarf194.htm @@ -0,0 +1,158 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas setpassword

+ + + + + + + + +

Purpose +

Changes the key field in an Authentication Database entry +

Synopsis +

kas setpassword -name <name of user>  [-new_password <new password>] 
+                [-kvno <key version number>] 
+                [-admin_username <admin principal to use for authentication>] 
+                [-password_for_admin <admin password>]  [-cell <cell name>] 
+                [-servers <explicit list of authentication servers>⁺]
+                [-noauth]  [-help]
+   
+kas setpasswd -na <name of user>  [-ne <new password>]  
+              [-k <key version number>]
+              [-a <admin principal to use for authentication>]  
+              [-p <admin password>]  [-c <cell name>]  
+              [-s <explicit list of authentication servers>⁺]  [-no]  [-h]
+   
+kas setp -na <name of user>  [-ne <new password>]  [-k <key version number>]
+         [-a <admin principal to use for authentication>]  
+         [-p <admin password>]  [-c <cell name>]  
+         [-s <explicit list of authentication servers>⁺]  [-no]  [-h]
+   
+kas sp -na <name of user>  [-ne <new password>]  [-k <key version number>]
+       [-a <admin principal to use for authentication >]  
+       [-p <admin password>]  [-c <cell name>]  
+       [-s <explicit list of authentication servers>⁺]  [-no]  [-h]
+

Description +

The kas setpassword command accepts a character string of +unlimited length, scrambles it into a form suitable for use as an encryption +key, places it in the key field of the Authentication Database entry named by +the -name argument, and assigns it the key version number specified +by the -kvno argument. +

To avoid making the password string visible at the shell prompt, omit the +-new_password argument. Prompts then appear at the shell +which do not echo the password visibly. +

When changing the afs server key, also issue bos +addkey command to add the key (with the same key version number) to the +/usr/afs/etc/KeyFile file. See the IBM AFS +Administration Guide for instructions. +

The command interpreter checks the password string subject to the following +conditions: +

If there is a program called kpwvalid in the same directory as +the kas binary, the command interpreter invokes it to process the +password. For details, see the kpwvalid reference +page. +
If the -reuse argument to the kas setfields command +has been used to prohibit reuse of previous passwords, the command interpreter +verifies that the password is not too similar too any of the user's +previous 20 passwords. It generates the following error message at the +shell: +
```
   Password was not changed because it seems like a reused password
+   
+
```
+
To prevent a user from subverting this restriction by changing the password +twenty times in quick succession (manually or by running a script), use the +-minhours argument on the kaserver initialization +command. The following error message appears if a user attempts to +change a password before the minimum time has passed: +
```
   Password was not changed because you changed it too 
+   recently; see your systems administrator
+   
+
```
+

Options +

-name +: Names the entry in which to record the new key. +
-new_password +: Specifies the character string the user types when authenticating to +AFS. Omit this argument and type the string at the resulting prompts so +that the password does not echo visibly. Note that some non-AFS +programs cannot handle passwords longer than eight characters. +
-kvno +: Specifies the key version number associated with the new key. +Provide an integer in the range from 0 through +255. If omitted, the default is 0 (zero), which is probably +not desirable for server keys. +
-admin_username +: Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +
-password_for_admin +: Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory kas reference page. +
-servers +: Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

In the following example, an administrator using the admin +account changes the password for pat (presumably because +pat forgot the former password or got locked out of his account in +some other way). +

   % kas setpassword pat
+   Password for admin:
+   new_password:
+   Verifying, please re-enter new_password:
+   
+

Privilege Required +

Individual users can change their own passwords. To change another +user's password or the password (server encryption key) for server +entries such as afs, the issuer must have the ADMIN flag +set in his or her Authentication Database entry. +

Related Information +

bos addkey +

kas +

kpwvalid +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf195.htm b/doc/html/AdminReference/auarf195.htm new file mode 100644 index 0000000..b82afe2 --- /dev/null +++ b/doc/html/AdminReference/auarf195.htm @@ -0,0 +1,123 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas statistics

+ + + + + + +

Purpose +

Displays statistics from an Authentication Server process +

Synopsis +

kas statistics [-admin_username <admin principal to use for authentication>]
+               [-password_for_admin <admin password>]  [-cell <cell name>] 
+               [-servers <explicit list of authentication servers>⁺]
+               [-noauth]  [-help]
+   
+kas sta [-a <admin principal to use for authentication>]  
+        [-p <admin password>]  [-c <cell name>]  
+        [-s <explicit list of authentication servers>⁺]  [-n]  [-h]  
+

Description +

The kas statistics command displays statistics from the +Authentication Server running on one of the cell's database server +machines. Use the -servers argument to name a specific +machine, or the command interpreter chooses one at random from all the +database server machines with which it has established connections. +

Cautions +

The -servers argument is not available in interactive mode, +making it impossible to specify a certain machine. +

Options +

-admin_username +: Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +
-password_for_admin +: Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory kas reference page. +
-servers +: Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The information in the output includes: +

The number of allocation and freeing operations the Authentication Server +has performed, and how many password change requests it has processed. +
An indication of its hash table use. +
The server machine's IP address in hexadecimal and the date when the +current instance of the Authentication Server started. +
The number of requests and aborted requests for various services: +authentication, ticket granting, password setting, entry listing, and so +on. +
The amount of CPU time that the Authentication Server has used to process +requests since it started. The amount is not accurate on all system +types, however. +
The number of entries in the Authentication Database that are marked with +the ADMIN flag. +

Examples +

In the following example, an administrator using the admin +account gathers statistics from the Authentication Server running on the +machine fs1.abc.com. +

   % kas statistics -servers fs1.abc.com
+   56 allocs, 46 frees, 0 password changes
+   Hash table utilization = 0.100000%
+   From host bfff21a7 started at Tue Mar 23 12:42:02 1999:
+     of 88 requests for Authenticate, 18 were aborted.
+     of 14 requests for GetTicket, 0 were aborted.
+     of 4 requests for CreateUser, 1 were aborted.
+     of 12 requests for SetFields, 4 were aborted.
+     of 3 requests for DeleteUser, 0 were aborted.
+     of 23 requests for GetEntry, 4 were aborted.
+     of 18 requests for ListEntry, 0 were aborted.
+     of 2 requests for GetStats, 1 were aborted.
+     of 2 requests for GetRandomKey, 0 were aborted.
+   Used 6.015 seconds of CPU time.
+   3 admin accounts
+   
+

Privilege Required +

The issuer must have the ADMIN flag set on his or her +Authentication Database entry. +

Related Information +

kas +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf196.htm b/doc/html/AdminReference/auarf196.htm new file mode 100644 index 0000000..80937fb --- /dev/null +++ b/doc/html/AdminReference/auarf196.htm @@ -0,0 +1,89 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas stringtokey

+ + + + + + +

Purpose +

Converts a character string into an octal key +

Synopsis +

kas stringtokey -string <password string>  [-cell <cell name>]  [-help]
+      
+kas str -s <password string>  [-c <cell name>]  [-h]
+

Description +

The kas stringtokey command converts the character string +specified with the -string argument into an octal string suitable +for use as an encryption key. +

The kas command interpreter generates the octal key by using an +encryption algorithm on the combination of the specified string and the name +of the local cell (as recorded in the local /usr/vice/etc/ThisCell +file). Use the -cell argument to convert a string into a key +appropriate for a cell other than the local one. +

Cautions +

This command writes the key to the standard output stream, on which it can +possibly be intercepted by third parties. It is not very secure to use +the key in an actual Authentication Database entry. +

Options +

-string +

Specifies the character string to convert into an octal key. +

-cell +

Specifies the complete Internet domain name of the cell to combine with +the password string while generating the key. If this argument is +omitted, the kas command interpreter determines the name of the +local cell by consulting: +

First, the value of the environment variable AFSCELL. +
Second, the cellname in the /usr/vice/etc/ThisCell file on the +local machine. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The output is of the following form: +

   Converting password string in realm 'cell_name' yields key='key'.
+   
+

Examples +

The following example shows the octal key equivalent of the string +new_pswd in the ABC Corporation cell. +

   % kas stringtokey new_pswd
+   Converting new_pswd in realm 'ABC.COM' yields
+       key='\346\307\364\320\263\233\342\354'.
+   
+

Privilege Required +

None, and no password is required. +

Related Information +

kas +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf197.htm b/doc/html/AdminReference/auarf197.htm new file mode 100644 index 0000000..227c9bf --- /dev/null +++ b/doc/html/AdminReference/auarf197.htm @@ -0,0 +1,99 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kas unlock

+ + + +

Purpose +

Unlocks a locked user account +

Synopsis +

kas unlock -name <authentication ID>  
+           [-admin_username <admin principal to use for authentication>] 
+           [-password_for_admin <admin password>]  [-cell <cell name>] 
+           [-servers <explicit list of authentication servers>⁺]
+           [-noauth]  [-help]
+         
+kas u -na <authentication ID>  
+      [-a <admin principal to use for authentication>] 
+      [-p <admin password>]  [-c <cell name>] 
+      [-s <explicit list of authentication servers>⁺]  [-no]  [-h]
+

Description +

The kas unlock command unlocks the Authentication Database entry +named by the -name argument. An entry becomes locked when +the user exceeds the limit on failed authentication attempts, generally by +providing the wrong password to either an AFS-modified login utility or the +klog command. Use the kas setfields command to +set the limit and the lockout time, and the kas examine command to +examine the settings. +

To unlock all locked user accounts at once, shutdown the +kaserver process on every database server machine, and remove the +/usr/afs/local/kaauxdb file from each one. The +kaserver process recreates the file as it restarts. +

Options +

-name +: Names the Authentication Database entry to unlock. +
-admin_username +: Specifies the user identity under which to authenticate with the +Authentication Server for execution of the command. For more details, +see the introductory kas reference page. +
-password_for_admin +: Specifies the password of the command's issuer. If it is +omitted (as recommended), the kas command interpreter prompts for +it and does not echo it visibly. For more details, see the introductory +kas reference page. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory kas reference page. +
-servers +: Names each machine running an Authentication Server with which to +establish a connection. For more details, see the introductory +kas reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory kas reference +page. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

In the following example, an administrator using the admin +account unlocks the entry for jones: +

   % kas unlock -name jones -admin_username admin
+   Administrator's (admin) Password:
+   
+

Privilege Required +

The issuer must have the ADMIN flag set on his or her +Authentication Database entry. +

Related Information +

kas +

kas setfields +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf198.htm b/doc/html/AdminReference/auarf198.htm new file mode 100644 index 0000000..09d071a --- /dev/null +++ b/doc/html/AdminReference/auarf198.htm @@ -0,0 +1,150 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kaserver

+ + + +

Purpose +

Initializes the Authentication Server +

Description +

kaserver [-noAuth]  [-fastKeys]  [-database <dbpath>] 
+         [-localfiles <lclpath>]  [-minhours <n>] 
+         [-servers <serverlist>]  [-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 kaserver command initializes the Authentication Server, +which runs on every database server machine. In the conventional +configuration, its binary file is located in the /usr/afs/bin +directory on a file server machine. +

The kaserver command is not normally issued at the command shell +prompt but rather placed into a file server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a database server machine as the local superuser +root. +

As it initializes, the Authentication Server process creates the two files +that constitute the Authentication Database, kaserver.DB0 +and kaserver.DBSYS1, in the /usr/afs/db directory +if they do not already exist. Use the commands in the kas +suite to administer the database. +

The Authentication Server is responsible for several aspects of AFS +security, including: +

Maintenance of all AFS server encryption keys and user passwords in the +Authentication Database. +
Creation of the tickets and tokens that users and servers use to establish +secure connections. Its Ticket Granting Service (TGS) component +performs this function. +

The Authentication Server records a trace of its activity in the +/usr/afs/logs/AuthLog file. Use the bos getlog +command to display the contents of the file. Use the kdb +command to read the protected files associated with the AuthLog +file, AuthLog.dir and AuthLog.pag. +

Options +

-noAuth +

Assigns the unprivileged identity anonymous to the +issuer. Thus, it establishes an unauthenticated connection between the +issuer and the Authentication Server. It is useful only when +authorization checking is disabled on the database server machine. In +normal circumstances, the Authentication Server allows only authorized +(privileged) users to issue commands that affect or contact the Authentication +Database and will refuse to perform such an action even if the +-noAuth flag is used. +

-fastKeys +

Is a test flag for use by the AFS Development staff; it serves no +functional purpose. +

-database +

Specifies the pathname of an alternate directory in which the +Authentication Database files reside. Provide the complete pathname, +ending in the base filename to which the .DB0 and +.DBSYS1 extensions are appended. For example, the +appropriate value for the default database files is +/usr/afs/db/kaserver. +

Provide the -localfiles argument along with this one; +otherwise, the -localfiles argument is also set to the value of +this argument, which is probably inappropriate. +

-localfiles +

Specifies the pathname of an alternate directory in which the auxiliary +Authentication Database file resides. Provide the complete pathname, +ending in the base filename to which the auxdb suffix is +appended. For example, the appropriate value for the default auxiliary +database file is /usr/afs/local/kaserver. +

-minhours +

Specifies the minimum number of hours that must pass between password +changes made by any regular user. System administrators (with the +ADMIN flag in their Authentication Database entry) can change +passwords as often as desired. Setting a minimum time between password +changes is not recommended. +

-servers +

Names each database server machine running an Authentication Server with +which the local Authentication Server is to synchronize its copy of the +Authentication Database , rather than with the machines listed in the local +/usr/afs/etc/CellServDB file. +

-enable_peer_stats +

-enable_process_stats +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following bos create command creates a kaserver +process on fs3.abc.com (the command appears on two +lines here only for legibility): +

   % bos create -server fs3.abc.com -instance kaserver \
+                -type simple -cmd /usr/afs/bin/kaserver
+

Privilege Required +

Related Information +

AuthLog +

kaserverauxdb +

bos +

AuthLog.dir, AuthLog.pag +

kas +

kdb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf199.htm b/doc/html/AdminReference/auarf199.htm new file mode 100644 index 0000000..cda0c61 --- /dev/null +++ b/doc/html/AdminReference/auarf199.htm @@ -0,0 +1,116 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kdb

+ + + +

Purpose +

Displays log or privileged actions performed by the Authentication Server +

Synopsis +

kdb [-dbmfile <dbmfile to use (default /usr/afs/logs/AuthLog)>]  
+    [-key <extract entries that match specified key>]  [-help]
+  
+

Description +

The kdb command displays the contents of the +AuthLog.dir and AuthLog.pag files +associated with the AuthLog file that resides on the local disk, by +default in the /usr/afs/logs directory. The files must exist +in that directory, which normally implies that the Authentication Server is +running on the machine. The files contain information on privileged +actions performed by the Authentication Server. +

Cautions +

It is possible that on some operating systems that AFS otherwise supports, +the Authentication Server cannot create the +/usr/afs/logs/AuthLog.dir and +/usr/afs/logs/AuthLog.pag files, making this command +inoperative. See the IBM AFS Release Notes for +details. +

Options +

-dbmfile +: Specifies the pathname of the file to display. Provide either a +complete pathname, a pathname relative to the /usr/afs/logs +directory, or a filename only, in which case the file must reside in the +/usr/afs/logs directory. Omit this argument to display +information from the AuthLog.dir and +AuthLog.pag files in the /usr/afs/logs +directory. +
-key +: Specifies each entry to be displayed from the indicated file. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The first line of output indicates the location of the files from which the +subsequent information is derived: +

   Printing all entries found in file_location
+

Each entry then includes the following two fields, separated by a +colon: +

user/server +

Identifies the user requesting the corresponding service and the server +that performed that service. In cases where no user is directly +involved, only the server appears; in cases where no server is directly +involved, only the user appears. +

service +

Identifies one of the following actions or services performed by the user +or server process. +

auth: Obtained a ticket-granting ticket +
chp: Changed a user password +
cruser: Created a user entry in the Authentication +Database +
delu: Deleted a user entry from the Authentication +Database +
gtck: Obtained a ticket other than a ticket-granting +ticket +
setf: Set fields in an Authentication Database entry +
unlok: Unlocked an Authentication Database entry +

The final line of output sums the number of entries. +

Examples +

The following example shows the output of the kdb command in the +ABC Corporation cell (abc.com): +

   % kdb
+   Printing all entries found in /usr/afs/logs/AuthLog
+   admin,krbtgt.ABC.COM:auth
+   admin,afs:gtck
+   admin:cruser
+   admin:delu
+   4 entries were found
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf200.htm b/doc/html/AdminReference/auarf200.htm new file mode 100644 index 0000000..55d0a07 --- /dev/null +++ b/doc/html/AdminReference/auarf200.htm @@ -0,0 +1,307 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

klog

+ + + + + + + +

Purpose +

Authenticates with the Authentication Server +

Synopsis +

klog  [-x]  [-principal <user name>]  [-password <user's password>]  
+      [-cell <cell name>]  [-servers <explicit list of servers>⁺]  
+      [-pipe]  [-silent]  [-lifetime <ticket lifetime in hh[:mm[:ss]]>]  
+      [-setpag]  [-tmp]  [-help]
+    
+klog  [-x]  [-pr <user name>]  [-pa <user's password>]  [-c <cell name>]  
+      [-s <explicit list of servers>⁺]  [-pi]  [-si]  
+      [-l <ticket lifetime in hh[:mm[:ss]]>]  [-se]  [-t]  [-h]
+

Description +

The klog command obtains an AFS token from the Authentication +Server. The Cache Manager on the local machine stores the token in a +credential structure in kernel memory and uses it when obtaining authenticated +access to the AFS filespace. This command does not affect the +issuer's identity (UNIX UID) in the local file system. +

By default, the command interpreter obtains a token for the AFS user name +that matches the issuer's identity in the local file system. To +specify an alternate user, include the -principal argument. +The user named by the -principal argument does not have to appear +in the local password file (the /etc/passwd file or +equivalent). +

By default, the command interpreter obtains a token for the local cell, as +defined by the AFSCELL environment variable set in the command shell or by the +/usr/vice/etc/ThisCell file on the local machine. To specify +an alternate cell, include the -cell argument. The command +interpreter contacts an Authentication Server chosen at random from the +cell's entry in the local /usr/afs/etc/CellServDB file, unless +the -servers argument is used to name one or more database server +machines. +

A user can have tokens in multiple cells simultaneously, but only one token +per cell per connection to the client machine. If the user's +credential structure already contains a token for the requested cell, the +token resulting from this command replaces it. +

Sites that employ standard Kerberos authentication instead of the AFS +Authentication Server must use the Kerberos version of this command, +klog.krb, on all client machines. It automatically +places the issuer's Kerberos tickets in the file named by the KRBTKFILE +environment variable, which the pagsh.krb command defines +automatically as /tmp/tktpX where X is the +number of the user's PAG. +

The lifetime of the token resulting from this command is the smallest of +the following. +

The lifetime specified by the issuer with the -lifetime +argument. If the issuer does not include this argument, the value +defaults to 720 hours (30 days). +
The maximum ticket lifetime recorded for the afs entry in the +Authentication Database. The default is 100 hours. +
The maximum ticket lifetime recorded in the specified user's +Authentication Database entry. The default is 25 hours for user entries +created by an Authentication Server running AFS 3.1 or later. +
The maximum ticket lifetime recorded in the +krbtgt.CELLNAME entry in the Authentication +Database; this entry corresponds to the ticket-granting ticket used +internally in generating the token. The default is 720 hours (30 +days). +

The output from the kas examine command displays an +Authentication Database entry's maximum ticket lifetime as Max +ticket lifetime. Administrators can display any entry, and users +can display their own entries. +

If none of the defaults have been changed, the token lifetime is 25 hours +for user accounts created by an Authentication Server running AFS 3.1 +or higher. The maximum lifetime for any token is 720 hours (30 days), +and the minimum is 5 minutes. +

Between the minimum and maximum values, the Authentication Server uses a +defined set of values, according to the following rules. Requested +lifetimes between 5 minutes and 10 hours 40 minutes are granted at 5 minute +intervals, rounding up. For example, if the issuer requests a lifetime +of 12 minutes, the token's actual lifetime is 15 minutes. +

For token lifetimes greater than 10 hours 40 minutes, consult the following +table, which presents all the possible times in units of +hours:minutes:seconds. +The number in parentheses is an approximation of the corresponding time in +days and hours (as indicated by the d and h +letters). For example, 282:22:17 means 282 +hours, 22 minutes, and 17 seconds, which translates to approximately 11 days +and 18 hours (11d 18h). The Authentication Server rounds up +a requested lifetime to the next highest possible lifetime. +

   11:24:15 (0d 11h)    46:26:01 (1d 22h)  189:03:38 (7d 21h)            
+   12:11:34 (0d 12h)    49:38:40 (2d 01h)  202:08:00 (8d 10h)            
+   13:02:09 (0d 13h)    53:04:37 (2d 05h)  216:06:35 (9d 00h)          
+   13:56:14 (0d 13h)    56:44:49 (2d 08h)  231:03:09 (9d 15h)         
+   14:54:03 (0d 14h)    60:40:15 (2d 12h)  247:01:43 (10d 07h)         
+   15:55:52 (0d 15h)    64:51:57 (2d 16h)  264:06:34 (11d 00h)           
+   17:01:58 (0d 17h)    69:21:04 (2d 21h)  282:22:17 (11d 18h)          
+   18:12:38 (0d 18h)    74:08:46 (3d 02h)  301:53:45 (12d 13h)           
+   19:28:11 (0d 19h)    79:16:23 (3d 07h)  322:46:13 (13d 10h)          
+   20:48:57 (0d 20h)    84:45:16 (3d 12h)  345:05:18 (14d 09h)           
+   22:15:19 (0d 22h)    90:36:53 (3d 18h)  368:56:58 (15d 08h)          
+   23:47:38 (0d 23h)    96:52:49 (4d 00h)  394:27:37 (16d 10h)         
+   25:26:21 (1d 01h)   103:34:45 (4d 07h)  421:44:07 (17d 13h)           
+   27:11:54 (1d 03h)   110:44:28 (4d 14h)  450:53:46 (18d 18h)           
+   29:04:44 (1d 05h)   118:23:54 (4d 22h)  482:04:24 (20d 02h)          
+   31:05:22 (1d 07h)   126:35:05 (5d 06h)  515:24:22 (21d 11h)          
+   33:14:21 (1d 09h)   135:20:15 (5d 15h)  551:02:38 (22d 23h) 
+   35:32:15 (1d 11h)   144:41:44 (6d 00h)  589:08:45 (24d 13h) 
+   37:59:41 (1d 13h)   154:42:01 (6d 10h)  629:52:56 (26d 05h) 
+   40:37:19 (1d 16h)   165:23:50 (6d 21h)  673:26:07 (28d 01h)
+   43:25:50 (1d 19h)   176:50:01 (7d 08h)
+   
+

Cautions +

By default, this command does not create a new process authentication group +(PAG); see the description of the pagsh command to learn about +PAGs. If a cell does not use an AFS-modified login utility, users must +include -setpag option to this command, or issue the +pagsh command before this one, to have their tokens stored in a +credential structure that is identified by PAG rather than by local +UID. +

When a credential structure is identified by local UID, the potential +security exposure is that the local superuser root can use the UNIX +su command to assume any other identity and automatically inherit +the tokens associated with that UID. Identifying the credential +structure by PAG eliminates this exposure. +

If the -password argument is used, the specified password cannot +begin with a hyphen, because it is interpreted as another option name. +Use of the -password argument is not recommended in any +case. +

By default, it is possible to issue this command on a properly configured +NFS client machine that is accessing AFS via the NFS/AFS Translator, assuming +that the NFS client machine is a supported system type. However, if the +translator machine's administrator has enabled UID checking by including +the -uidcheck on argument to the fs exportafs command, +the command fails with an error message similar to the following: +

   
+   Warning: Remote pioctl to translator_machine  has failed (err=8). . . 
+   Unable to authenticate to AFS because a pioctl failed.
+

Enabling UID checking means that the credential structure in which tokens +are stored on the translator machine must be identified by a UID that matches +the local UID of the process that is placing the tokens in the credential +structure. After the klog command interpreter obtains the +token on the NFS client, it passes it to the remote executor daemon on the +translator machine, which makes the system call that stores the token in a +credential structure on the translator machine. The remote executor +generally runs as the local superuser root, so in most cases its +local UID (normally zero) does not match the local UID of the user who issued +the klog command on the NFS client machine. +

Issuing the klog command on an NFS client machine creates a +security exposure: the command interpreter passes the token across the +network to the remote executor daemon in clear text mode. +

Options +

-x +

Appears only for backwards compatibility. Its former function is +now the default behavior of this command. +

-principal +

Specifies the user name to authenticate. If this argument is +omitted, the Authentication Server attempts to authenticate the user logged +into the local file system. +

-password +

Specifies the issuer's password (or that of the alternate user +identified by the -principal argument). Omit this argument +to have the command interpreter prompt for the password, in which case it does +not echo visibly in the command shell. +

-cell +

Specifies the cell for which to obtain a token. The command is +directed to that cell's Authentication Servers. During a single +login session on a given machine, a user can be authenticated in multiple +cells simultaneously, but can have only one token at a time for each of them +(that is, can only authenticate under one identity per cell per session on a +machine). It is acceptable to abbreviate the cell name to the shortest +form that distinguishes it from the other cells listed in the +/usr/vice/etc/CellServDB file on the client machine on which the +command is issued. +

If this argument is omitted, the command is executed in the local cell, as +defined +

First, by the value of the environment variable AFSCELL +
Second, in the /usr/vice/etc/ThisCell file on the client +machine on which the command is issued +

-servers +

Establishes a connection with the Authentication Server running on each +specified database server machine. The command interpreter then chooses +one of these at random to execute the command. It is best to provide +fully-qualified hostnames, but abbreviated forms are possibly acceptable +depending on the state of the cell's name server at the time the command +is issued. This option is useful for testing specific servers if +problems are encountered. +

If this argument is omitted, the command interpreter establishes a +connection with each machine listed for the indicated cell in the local copy +of the /usr/vice/etc/CellServDB file, and then chooses one of them +at random for command execution. +

-pipe +

Suppresses all output to the standard output stream, including prompts and +error messages. The klog command interpreter expects to +receive the password from the standard input stream. Do not use this +argument; it is designed for use by application programs rather than +human users. +

-silent +

Suppresses some of the trace messages that the klog command +produces on the standard output stream by default. It still reports on +major problems encountered. +

-lifetime +

Requests a specific lifetime for the token. Provide a number of +hours and optionally minutes and seconds in the format +hh[:mm[:ss]]. +The value is used in calculating the token lifetime as described in the +Description section. +

-setpag +

Creates a process authentication group (PAG) prior to requesting +authentication. The token is associated with the newly created +PAG. +

-tmp +

Creates a Kerberos-style ticket file in the /tmp directory of +the local machine. The file is called +tkt.AFS_UID where AFS_UID is the AFS UID +of the issuer. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Cautions +

Output +

The following message indicates that the limit on consecutive +authentication failures has been exceeded. An administrator can use the +kas unlock command to unlock the account, or the issuer can wait +until the lockout time for the account has passed. (The time is set +with the -locktime argument to the kas setfields command +and displayed in the output from the kas examine command). +

   
+   Unable to authenticate to AFS because ID is locked - see your system admin
+   
+

If the -tmp flag is included, the following message confirms +that a Kerberos-style ticket file was created: +

   
+   Wrote ticket file to /tmp
+   
+

Examples +

Most often, this command is issued without arguments. The +appropriate password is for the person currently logged into the local file +system. The ticket's lifetime is calculated as described in the +Description section (if no defaults have been changed, it is 25 +hours for a user whose Authentication Database entry was created in AFS +3.1 or later). +

   
+   % klog
+   Password: 
+   
+

The following example authenticates the user as admin in the ABC +Corporation's test cell: +

   
+   % klog -principal admin -cell test.abc.com
+   Password: 
+   
+

In the following, the issuer requests a ticket lifetime of 104 hours 30 +minutes (4 days 8 hours 30 minutes). Presuming that this lifetime is +allowed by the maximum ticket lifetimes and other factors described in the +Description section, the token's lifetime is +110:44:28, which is the next largest possible value. +

      % klog -lifetime 104:30
+   Password: 
+   
+

Privilege Required +

None +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf201.htm b/doc/html/AdminReference/auarf201.htm new file mode 100644 index 0000000..a9b66bb --- /dev/null +++ b/doc/html/AdminReference/auarf201.htm @@ -0,0 +1,178 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

knfs

+ + + + +

Purpose +

Establishes basis for authenticated access to AFS from a non-supported NFS +client using the NFS/AFS Translator +

Synopsis +

knfs -host <host name>  [-id <user ID (decimal)>]
+     [-sysname <host's '@sys' value>]  [-unlog]  [-tokens]  [-help]
+    
+knfs -ho <host name>  [-i <user ID (decimal)>]  
+     [-s <host's '@sys' value>]  [-u]  [-t]  [-he]
+

Description +

The knfs command creates an AFS credential structure on the +local machine, identifying it by a process authentication group (PAG) number +associated with the NFS client machine named by the -hostname +argument and by default with a local UID on the NFS client machine that +matches the issuer's local UID on the local machine. It places in +the credential structure the AFS tokens that the issuer has previously +obtained (by logging onto the local machine if an AFS-modified login utility +is installed, by issuing the klog command, or both). To +associate the credential structure with an NFS UID that does not match the +issuer's local UID, use the -id argument. +

Issue this command only on the NFS^(R)/AFS translator machine that is +serving the NFS client machine, after obtaining AFS tokens on the translator +machine for every cell to which authenticated access is required. The +Cache Manager on the translator machine uses the tokens to obtain +authenticated AFS access for the designated user working on the NFS client +machine. This command is not effective if issued on an NFS client +machine. +

To enable the user on the NFS client machine to issue AFS commands, use the +-sysname argument to specify the NFS client machine's system +type, which can differ from the translator machine's. The NFS +client machine must be a system type for which AFS is supported. +

The -unlog flag discards the tokens in the credential structure, +but does not destroy the credential structure itself. The Cache Manager +on the translator machine retains the credential structure until the next +reboot, and uses it each time the issuer accesses AFS through the translator +machine. The credential structure only has tokens in it if the user +reissues the knfs command on the translator machine each time the +user logs into the NFS client machine. +

To display the tokens associated with the designated user on the NFS client +machine, include the -tokens flag. +

Users working on NFS client machines of system types for which AFS binaries +are available (and for which the cell has purchased a license) can use the +klog command rather than the knfs command. +

Cautions +

If the translator machine's administrator has enabled UID checking by +issuing the fs exportafs command with the -uidcheck on +argument, it is not possible to use the -id argument to assign the +tokens to an NFS UID that differs from the issuer's local UID. In +this case, there is no point in including the -id argument, because +the only acceptable value (the issuer's local UID) is the value used when +the -id argument is omitted. Requiring matching UIDs is +effective only when users have the same local UID on the translator machine as +on NFS client machines. In that case, it guarantees that users assign +their tokens only to their own NFS sessions. +

This command does not make it possible for users working on non-supported +system types to issue AFS commands. This is possible only on NFS +clients of a system type for which AFS is available. +

Options +

-host +: Names the NFS client machine on which the issuer is to work. +Providing a fully-qualified hostname is best, but abbreviated forms are +possibly acceptable depending on the state of the cell's name server at +the time the command is issued. +
-id +: Specifies the local UID on the NFS client to which to assign the +tokens. The NFS client identifies file requests by the NFS UID, so +creating the association enables the Cache Manager on the translator machine +to use the appropriate tokens when filling the requests. If this +argument is omitted, the command interpreter uses an NFS UID that matches the +issuer's local UID on the translator machine (as returned by the +getuid function). +
-sysname +: Specifies the value that the local (translator) machine's remote +executor daemon substitutes for the @sys variable in pathnames when +executing AFS commands issued on the NFS client machine (which must be a +supported system type). If the NFS user's PATH environment +variable uses the @sys variable in the pathnames for directories +that house AFS binaries (as recommended), then setting this argument enables +NFS users to issue AFS commands by leading the remote executor daemon to +access the AFS binaries appropriate to the NFS client machine even if its +system type differs from the translator machine's. +
-unlog +: Discards the tokens stored in the credential structure identified by the +PAG associated with the -host argument and, optionally, the +-id argument. +
-tokens +: Displays the AFS tokens assigned to the designated user on the indicated +NFS client machine. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The following error message indicates that UID checking is enabled on the +translator machine and that the value provided for the -id argument +differs from the issuer's local UID. +

   
+   knfs: Translator in 'passwd sync' mode; remote uid must be the same as local uid
+

Examples +

The following example illustrates a typical use of this command. The +issuer smith is working on the machine +nfscli1.abc.com and has user ID 1020 on +that machine. The translator machine +tx4.abc.com uses an AFS-modified login utility, so +smith obtains tokens for the ABC Corporation cell automatically +upon login via the telnet program. She then issues the +klog command to obtain tokens as admin in the ABC +Corporation's test cell, test.abc.com, and the +knfs command to associate both tokens with the credential structure +identified by machine name nfs-cli1 and user ID +1020. She breaks the connection to tx4 and works +on nfscli1. +

   % telnet tx4.abc.com
+   . . .
+   login: smith
+   Password:
+   AFS(R) login
+   
+   % klog admin -cell test.abc.com
+   Password:
+   
+   % knfs nfscli1.abc.com 1020
+   
+   % exit
+   
+

The following example shows user smith again connecting to the +machine tx4 via the telnet program and discarding the +tokens. +

   % telnet translator4.abc.com
+   . . .
+   login: smith
+   Password:
+   AFS(R) login
+   
+   % knfs nfscli1.abc.com 1020 -unlog
+ 
+   % exit
+

Privilege Required +

None +

Related Information +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf202.htm b/doc/html/AdminReference/auarf202.htm new file mode 100644 index 0000000..d75c48d --- /dev/null +++ b/doc/html/AdminReference/auarf202.htm @@ -0,0 +1,164 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kpasswd

+ + + + + + + +

Purpose +

Changes the issuer's password in the Authentication Database +

Synopsis +

kpasswd [-x]  [-principal <user name>]  [-password <user's password>]
+        [-newpassword <user's new password>]  [-cell <cell name>]
+        [-servers <explicit list of servers>⁺]  [-pipe]  [-help]
+   
+kpasswd [-x]  [-pr <user name>]  [-pa <user's password>]  
+        [-n <user's new password>]  [-c <cell name>]  
+        [-s <explicit list of servers>⁺]  [-pi]  [-h] 
+

Description +

The kpasswd command changes the password recorded in an +Authentication Database entry. By default, the command interpreter +changes the password for the AFS user name that matches the issuer's +local identity (UNIX UID). To specify an alternate user, include the +-principal argument. The user named by the +-principal argument does not have to appear in the local password +file (the /etc/passwd file or equivalent). +

By default, the command interpreter sends the password change request to +the Authentication Server running on one of the database server machines +listed for the local cell in the /usr/afs/etc/CellServDB file on +the local disk; it chooses the machine at random. It consults the +/usr/vice/etc/ThisCell file on the local disk to learn the local +cell name. To specify an alternate cell, include the -cell +argument. +

Unlike the UNIX passwd command, the kpasswd command +does not restrict passwords to eight characters or less; it accepts +passwords of virtually any length. All AFS commands that require +passwords (including the klog, kpasswd, and AFS-modified +login utilities, and the commands in the kas suite) accept +passwords longer than eight characters, but some other applications and +operating system utilities do not. Selecting an AFS password of eight +characters or less enables the user to maintain matching AFS and UNIX +passwords. +

The command interpreter makes the following checks: +

If the program kpwvalid exists in the same directory as the +kpasswd command, the command interpreter pass the new password to +it for verification. For details, see the kpwvalid reference +page. +
If the -reuse argument to the kas setfields command +has been used to prohibit reuse of previous passwords, the command interpreter +verifies that the password is not too similar too any of the user's +previous 20 passwords. It generates the following error message at the +shell: +
```
   Password was not changed because it seems like a reused password
+   
+
```
+
To prevent a user from subverting this restriction by changing the password +twenty times in quick succession (manually or by running a script), use the +-minhours argument on the kaserver initialization +command. The following error message appears if a user attempts to +change a password before the minimum time has passed: +
```
   Password was not changed because you changed it too 
+   recently; see your systems administrator
+
```
+

Options +

-x +

Appears only for backwards compatibility. +

-principal +

Names the Authentication Database entry for which to change the +password. If this argument is omitted, the database entry with the same +name as the issuer's local identity (UNIX UID) is changed. +

-password +

Specifies the current password. Omit this argument to have the +command interpreter prompt for the password, which does not echo +visibly: +

   Old password: current_password
+   
+

-newpassword +

Specifies the new password, which the kpasswd command +interpreter converts into an encryption key (string of octal numbers) before +sending it to the Authentication Server for storage in the user's +Authentication Database entry. +

Omit this argument to have the command interpreter prompt for the password, +which does not echo visibly: +

   New password (RETURN to abort): new_password 
+   Retype new password: new_password
+   
+

-cell +

Specifies the cell in which to change the password, by directing the +command to that cell's Authentication Servers. The issuer can +abbreviate the cell name to the shortest form that distinguishes it from the +other cells listed in the local /usr/vice/etc/CellServDB +file. +

By default, the command is executed in the local cell, as defined +

First, by the value of the environment variable AFSCELL +
Second, in the /usr/vice/etc/ThisCell file on the client +machine on which the command is issued +

-servers +

Establishes a connection with the Authentication Server running on each +specified machine, rather than with all of the database server machines listed +for the relevant cell in the local copy of the +/usr/vice/etc/CellServDB file. The kpasswd +command interpreter then sends the password-changing request to one machine +chosen at random from the set. +

-pipe +

Suppresses all output to the standard output stream or standard error +stream. The kpasswd command interpreter expects to receive +all necessary arguments, each on a separate line, from the standard input +stream. Do not use this argument, which is provided for use by +application programs rather than human users. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example shows user pat changing her password in +the ABC Corporation cell. +

   % kpasswd
+   Changing password for 'pat' in cell 'abc.com'.
+   Old password:
+   New password (RETURN to abort):
+   Verifying, please re-enter new_password:
+   
+

Privilege Required +

None +

Related Information +

kas setfields +

kas setpassword +

klog +

kpwvalid +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf203.htm b/doc/html/AdminReference/auarf203.htm new file mode 100644 index 0000000..51ba7ea --- /dev/null +++ b/doc/html/AdminReference/auarf203.htm @@ -0,0 +1,88 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

kpwvalid

+ + + +

Purpose +

Checks quality of new password +

Description +

The kpwvalid command checks the quality of a new password passed +to it from the kpasswd or kas setpassword +command. It is optional. If it exists, it must reside in the +same AFS directory as the binaries for the kpasswd and +kas command suites (create a symbolic link from the client +machine's local disk to this directory). The directory's ACL +must extend the a (administer) and w +(write) permissions to the system:administrators +group only. These requirements prevent unauthorized users from +substituting a spurious kpwvalid binary. +

The AFS distribution includes an example kpwvalid program that +checks that the password is at least eight characters long; the code for +it appears in the following Examples section. +

The script or program must accept a sequence of password strings, one per +line, on the standard input stream. The first is the current password +and is ignored. Each subsequent string is a candidate password to be +checked. The program must write the following to the standard output +stream for each one: +

0 (zero) and a newline character to indicate that the password +is acceptable +
A non-zero decimal number and a newline character to indicate that the +password is not acceptable +

Further, it must write any error messages only to the standard error +stream, not to the standard output stream. +

Examples +

The following example program, included in the AFS distribution, verifies +that the requested password includes eight or more characters. +

   #include <stdio.h>
+   /* prints 0 if the password is long enough, otherwise non-zero */
+   main()
+   {
+   char oldpassword[512];
+   char password[512];
+   
+   if (fgets(oldpassword, 512, stdin))
+      while (fgets(password, 512, stdin)) {
+         if (strlen(password) > 8) { /* password includes a newline */
+            fputs("0\n",stdout);
+            fflush(stdout);
+         }
+         else {
+            fputs("Passwords must contain at least 8 characters.\n",
+                  stderr);
+            fputs("1\n",stdout);
+            fflush(stdout);
+         }
+   return 0;
+   }
+   
+

Related Information +

kas setpassword +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf204.htm b/doc/html/AdminReference/auarf204.htm new file mode 100644 index 0000000..c6e14b2 --- /dev/null +++ b/doc/html/AdminReference/auarf204.htm @@ -0,0 +1,155 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

package

+ + + + + + + +

Purpose +

Configures files and directories on the local disk +

Synopsis +

package [initcmd]  [-config <base name of configuration file>]
+   [-fullconfig <full name of configuration file, or stdin for standard input>]
+   [-overwrite]  [-noaction]  [-verbose]  [-silent]  [-rebootfiles]  
+   [-debug]  [-help]
+    
+package [i]  [-c <base name of configuration file>]
+        [-f <full name of configuration file, or stdin for standard input>]
+        [-o]  [-n]  [-v]  [-s]  [-r]  [-d]  [-h]
+

Description +

The package command configures the machine's local disk to +comply with the instructions in the configuration file named by the +-config or -fullconfig argument. +

By default, the package command alters any existing local disk +element whose contents or configuration does not match the element defined in +the configuration file. For example, if a configuration file +D instruction defines a directory that has the same name as a +symbolic link on the local disk, the package command replaces the +symbolic link with the directory. The F and L +instructions include an optional update_code field that alters this +behavior. +

Also by default, the package command takes no action on elements +on the local disk that are not mentioned in the configuration file. Use +the D instruction's R update code to remove files +from the disk directory that are not mentioned in the configuration +file. +

Before running the package command, the administrator must +create the template file and other files on the local disk. For +instructions, see the IBM AFS Administration Guide. +

It is not possible to configure a remote client machine's disk using +this command. +

Cautions +

The package command interpreter exits without executing any +instruction if there are any syntax errors or incorrect values in the +configuration file. +

Options +

initcmd +

Accommodates the command's use of the AFS command parser, and is +optional. +

-config +

Specifies the pathname of the configuration file to use, ending in the +file's base name, which omits the suffix that indicates the machine +type. The package command determines the machine's +system type name and automatically appends it to the base name. An +example of the proper value for this argument is staff rather than +staff.rs_aix42. Partial pathnames are interpreted +relative to the current working directory. +

Provide this argument or the -fullconfig argument. +

-fullconfig +

Specifies the configuration file to use. Two types of values are +acceptable: +

The full pathname of the configuration file to use, complete with an +extension indicating the machine type (examples: +staff.rs_aix42, admin.sun4x_56). +
The string stdin to indicate that the issuer is providing +configuration information via the standard input stream, either by piping in +the contents of a file, or by typing configuration lines at the shell. +In the latter case, type <Ctrl-d> to conclude the input. +

Provide this argument or the -config argument. +

-overwrite +

Overwrites elements on the local disk with the source version indicated in +the configuration file, even if the owner write (w) mode +bit is turned on the disk element. Files protected by the I +update code on an F line in the configuration file are not +overwritten. +

-noaction +

Checks the sequence of operations to be performed when the command +actually runs and reports any problems that the package command +interpreter expects to encounter. No elements on the local disk or in +AFS are changed. If the -verbose flag is also provided, the +trace includes all actions to be performed as well as anticipated +errors. +

-silent +

Suppresses some of the trace messages sent to the standard output stream +by default. The output still reports major problems. +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-rebootfiles +

Prevents overwriting of any file marked with the Q update code +on an F line in the configuration file. This effectively +prevents the machine from rebooting automatically again when the +package command is invoked in the machine's AFS initialization +file. +

-debug +

Enables debugging output, which is directed to the standard output stream +by default. By default, no debugging output is produced. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

This command is usually invoked in a client machine's AFS +initialization file (/etc/rc or equivalent), rather than issued at +the command shell prompt. +

The following command invokes the version of the staff +configuration file appropriate for this machine's system type, and +produces verbose output. +

   # /etc/package -c staff -v
+   
+

The following example uses the configuration file whose basename is defined +in the /.package file on the local machine. This +method enables the administrator to use the same package command in +every machine's AFS initialization file but still customize configuration +by putting the appropriate basename in the /.package +file. +

   # /etc/package -c `cat /.package` -v
+   
+

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf205.htm b/doc/html/AdminReference/auarf205.htm new file mode 100644 index 0000000..f9a4c4c --- /dev/null +++ b/doc/html/AdminReference/auarf205.htm @@ -0,0 +1,72 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

package apropos

+ + + +

Purpose +

Displays each help entry containing a keyword string +

Synopsis +

package apropos [-topic <help string>]  [-help]
+   
+package a [-t <help string>]  [-h]
+

Description +

The package apropos command displays the first line of the +online help entry for any package 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 package 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 +package command where the string specified with the +-topic argument is part of the command name or first line. +

Examples +

The following command lists all package commands that include +the word help in their names or short descriptions: +

   % package apropos help
+   apropos: search by help text
+   help: get help on commands
+   
+

Privilege Required +

None +

Related Information +

package help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf206.htm b/doc/html/AdminReference/auarf206.htm new file mode 100644 index 0000000..2b0fb27 --- /dev/null +++ b/doc/html/AdminReference/auarf206.htm @@ -0,0 +1,88 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

package help

+ + + +

Purpose +

Displays the syntax of specified package commands or lists +functional descriptions of all package commands +

Synopsis +

package help [-topic <help string>⁺]  [-help]
+   
+package h [-t <help string>⁺]  [-h]
+

Description +

The package help command displays the complete online help entry +(short description and syntax statement) for each command operation code +specified by the -topic argument. If the -topic +argument is omitted, the output includes the first line (name and short +description) of the online help entry for every package +command. +

To list every package command whose name or short description +includes a specified keyword, use the package apropos +command. +

Options +

-topic +: Indicates each command for which to display the complete online help +entry. Omit the package part of the command name, providing +only the operation code (for example, specify initcmd, not +package initcmd). If this argument is omitted, the output +briefly describes every package command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each package command consists of the +following two or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following command displays the online help entry for the package +initcmd command: +

   % package help initcmd
+   package initcmd: initialize the program
+   Usage: package [initcmd] [-config <base name of configuration file>]  
+   [-fullconfig <full name of configuration file, or stdin for standard input>] 
+   [-overwrite] [-noaction] [-verbose] [-silent] [-rebootfiles] 
+   [-debug] [-help]
+   
+

Privilege Required +

None +

Related Information +

package apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf207.htm b/doc/html/AdminReference/auarf207.htm new file mode 100644 index 0000000..1de5b33 --- /dev/null +++ b/doc/html/AdminReference/auarf207.htm @@ -0,0 +1,58 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

package_test

+ + + +

Purpose +

Tests the validity of a package configuration file +

Synopsis +

package_test <config file>
+

This command does not use the syntax conventions of the AFS command +suites. Provide the command name in full. +

Description +

The package_test command tests the validity of a +package configuration file created when a prototype file is +compiled. The command interpreter prints error messages on the standard +output stream. +

Options +

config file +: Specifies the package configuration file to validate. +

Examples +

The following example tests the validity of the package +configuration file staff.sun4x_56. +

   % package_test staff.sun4x_56
+   
+

Privilege Required +

None +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf208.htm b/doc/html/AdminReference/auarf208.htm new file mode 100644 index 0000000..5ee36e7 --- /dev/null +++ b/doc/html/AdminReference/auarf208.htm @@ -0,0 +1,121 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pagsh

+ + + + +

Purpose +

Creates a new PAG +

Synopsis +

pagsh
+

Description +

The pagsh command creates a new command shell (owned by the +issuer of the command) and associates a new process authentication +group (PAG) with the shell and the user. A PAG is a number +guaranteed to identify the issuer of commands in the new shell uniquely to the +local Cache Manager. The PAG is used, instead of the issuer's UNIX +UID, to identify the issuer in the credential structure that the Cache Manager +creates to track each user. +

Any tokens acquired subsequently (presumably for other cells) become +associated with the PAG, rather than with the user's UNIX UID. +This method for distinguishing users has two advantages. +

It means that processes spawned by the user inherit the PAG and so share +the token; thus they gain access to AFS as the authenticated user. +In many environments, for example, printer and other daemons run under +identities (such as the local superuser root) that the AFS server +processes recognize only as anonymous. Unless PAGs are used, +such daemons cannot access files in directories whose access control lists +(ACLs) do not extend permissions to the system:anyuser +group. +
It closes a potential security loophole: UNIX allows anyone already +logged in as the local superuser root on a machine to assume any +other identity by issuing the UNIX su command. If the +credential structure is identified by a UNIX UID rather than a PAG, then the +local superuser root can assume a UNIX UID and use any tokens +associated with that UID. Use of a PAG as an identifier eliminates that +possibility. +

Note:

The pagsh.krb version of this command is intended for use +by sites that employ standard Kerberos authentication for their +clients. The pagsh.krb command provides all the +functionality of the pagsh command. In addition, it defines +the environment variable KRBTKFILE (which specifies the storage location of +Kerberos tickets) to be the /tmp/tktpX file (where +X is the number of the user's PAG). The functionality of +this command supports the placement of Kerberos tickets by the +klog.krb command and Kerberized AFS-modified login utilities +in the file specified by the environment variable KRBTKFILE. +

Cautions +

Each PAG created uses two of the memory slots that the kernel uses to +record the UNIX groups associated with a user. If none of these slots +are available, the pagsh command fails. This is not a +problem with most operating systems, which make at least 16 slots available +per user. +

In cells that do not use an AFS-modified login utility, use this command to +obtain a PAG before issuing the klog command (or include the +-setpag argument to the klog command). If a PAG +is not acquired, the Cache Manager stores the token in a credential structure +identified by local UID rather than PAG. This creates the potential +security exposure described in the Description section. +

If users of NFS client machines for which AFS is supported are to issue +this command as part of authenticating with AFS, do not use the fs +exportafs command's -uidcheck on argument to enable UID +checking on NFS/AFS Translator machines. Enabling UID checking prevents +this command from succeeding. See the reference page for the +klog command. +

If UID checking is not enabled on Translator machines, then by default it +is possible to issue this command on a properly configured NFS client machine +that is accessing AFS via the NFS/AFS Translator, assuming that the NFS client +machine is a supported system type. The pagsh binary +accessed by the NFS client must be owned by, and grant setuid privilege to, +the local superuser root. The complete set of mode bits must +be -rwsr-xr-x. This is not a requirement when the command is +issued on AFS client machines. +

However, if the translator machine's administrator has enabled UID +checking by including the -uidcheck on argument to the fs +exportafs command, the command fails with an error message similar to +the following: +

   
+   Warning: Remote setpag to translator_machine  has failed (err=8). . . 
+   setpag: Exec format error
+

Examples +

In the following example, the issuer invokes the C shell instead of the +default Bourne shell: +

   # pagsh -c /bin/csh
+   
+

Privilege Required +

None +

Related Information +

fs exportafs +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf209.htm b/doc/html/AdminReference/auarf209.htm new file mode 100644 index 0000000..09453b2 --- /dev/null +++ b/doc/html/AdminReference/auarf209.htm @@ -0,0 +1,89 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

prdb_check

+ + + +

Purpose +

Checks the integrity of the Protection Database +

Synopsis +

prdb_check -database <ptdb_file>  [-uheader]  [-pheader]  [-entries]  
+           [-verbose]  [-help]
+   
+prdb_check -d <ptdb_file>  [-u]  [-p]  [-e]  [-v]  [-h]
+

Description +

The prdb_check command checks the integrity of the Protection +Database, reporting any errors or corruption it finds. If there are +problems, do not issue any pts commands until the database is +repaired. +

Cautions +

The results can be unpredictable if the Protection Server makes changes to +the Protection Database while this command is running. Use the bos +shutdown command to shutdown the local ptserver process +before running this command, or before creating a second copy of the +prdb.DB0 file (with a different name) on which to run the +command. +

Options +

-database +: Names the Protection Database (copy of the prdb.DB0 +file) to check. If the current working directory is not the location of +the file, provide a pathname, either full or relative to the current working +directory. +
-uheader +: Displays information which Ubik maintains in the database's +header. +
-pheader +: Displays information which the Protection Server maintains in the +database's header. +
-entries +: Outputs every entry in the database. Some of the information is +similar to that returned by the pts examine command. +
-verbose +: Reports additional information about the database, including the number of +entries in the database and a trace of the internal database structures the +command is verifying. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

bos shutdown +

pts examine +

ptserver +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf210.htm b/doc/html/AdminReference/auarf210.htm new file mode 100644 index 0000000..e3bd837 --- /dev/null +++ b/doc/html/AdminReference/auarf210.htm @@ -0,0 +1,149 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts

+ + + + + + + + + + + +

Purpose +

Introduction to the pts command suite +

Description +

The commands in the pts command suite are the administrative +interface to the Protection Server, which runs on each database server machine +in a cell and maintains the Protection Database. The database stores +the information that AFS uses to augment and refine the standard UNIX scheme +for controlling access to files and directories. +

Instead of relying only on the mode bits that define access rights for +individual files, AFS associates an access control list (ACL) with each +directory. The ACL lists users and groups and specifies which of seven +possible access permissions they have for the directory and the files it +contains. (It is still possible to set a directory or file's mode +bits, but AFS interprets them in its own way; see the chapter on +protection in the IBM AFS Administration Guide for details.) +

AFS enables users to define groups in the Protection Database and place +them on ACLs to extend a set of rights to multiple users +simultaneously. Groups simplify administration by making it possible to +add someone to many ACLs by adding them to a group that already exists on +those ACLs. Machines can also be members of a group, so that users +logged into the machine automatically inherit the permissions granted to the +group. +

There are several categories of commands in the pts command +suite: +

Commands to create and remove Protection Database entries: pts +creategroup, pts createuser, and pts delete +
Commands to administer and display group membership: pts +adduser, +
pts listowned, pts membership, and pts +removeuser +
Commands to administer and display properties of user and group entries +other than membership: pts chown, pts examine, +pts listentries, pts rename, and pts +setfields +
Commands to set and examine the counters used when assigning IDs to users +and groups: pts listmax and pts setmax +
Commands to obtain help: pts apropos and pts +help +

Options +

The following arguments and flags are available on many commands in the +pts suite. The reference page for each command also lists +them, but they are described here in greater detail. +

-cell <cell name> +

The value of the AFSCELL environment variable +
The local /usr/vice/etc/ThisCell file +

-force +

+ +Enables the command to continue executing as far as possible when errors or +other problems occur, rather than halting execution immediately. +Without it, the command halts as soon as the first error is +encountered. In either case, the pts command interpreter +reports errors at the command shell. This flag is especially useful if +the issuer provides many values for a command line argument; if one of +them is invalid, the command interpreter continues on to process the remaining +arguments. + +

-help +

-noauth +

+ +Establishes an unauthenticated connection to the Protection Server, in which +the server treats the issuer as the unprivileged user +anonymous. It is useful only when authorization checking is +disabled on the server machine (during the installation of a file server +machine or when the bos setauth command has been used during other +unusual circumstances). In normal circumstances, the Protection Server +allows only privileged users to issue commands that change the Protection +Database, and refuses to perform such an action even if the -noauth +flag is provided. +

Privilege Required +

Members of the system:administrators group can issue all +pts commands on any entry in the Protection Database. +

Users who do not belong to the system:administrators group +can list information about their own entry and any group entries they +own. The privacy flags set with the pts setfields command +control access to entries owned by other users. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf211.htm b/doc/html/AdminReference/auarf211.htm new file mode 100644 index 0000000..129f88d --- /dev/null +++ b/doc/html/AdminReference/auarf211.htm @@ -0,0 +1,121 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts adduser

+ + + + + + + + + +

Purpose +

Adds a user or machine to a Protection Database group +

Synopsis +

pts adduser -user <user name>⁺  -group <group name>⁺ 
+            [-cell <cell name>]  [-noauth]  [-force]  [-help]
+   
+pts ad -u <user name>⁺  -g <group name>⁺  [-c <cell name>]  [-n]  [-f]  [-h]
+

Description +

The pts adduser command adds each user or machine entry named by +the -user argument as a member of each group named by the +-group argument. +

To remove members of a group, use the pts removeuser +command. To list the groups to which a user or machine belongs, or the +members of a specified group, use the pts membership +command. +

Cautions +

After being added as a group member, a currently authenticated user must +reauthenticate (for example, by issuing the klog command) to obtain +permissions granted to the group on an access control list (ACL). +

Options +

-user +: Specifies the name of each user or machine entry to add to each group +named by the -group argument. The name of a machine entry +resembles an IP address and can use the wildcard notation described on the +pts createuser reference page. The user or machine entry +must already exist in the Protection Database. +
-group +: Specifies the complete name (including the owner prefix if applicable) of +each group to which to add members. The group entry must already exist +in the Protection Database. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example adds user smith to the group +system:administrators. +

   % pts adduser -user smith -group system:administrators
+   
+

The following example adds users jones, terry, and +pat to the smith:colleagues group. +

   % pts adduser -user jones terry pat -group smith:colleagues
+   
+

The following example adds the machine entries in the ABC Corporation +subnet to the group bin-prot. Because of the IP address +range of the ABC Corporation subnet, the system administrator was able to +group the machines into three machine entries (using the wildcard notation +discussed on the pts createuser reference page). +

   % pts adduser -user 138.255.0.0 192.12.105.0 192.12.106.0 -group bin-prot
+   
+

Privilege Required +

The required privilege depends on the setting of the fourth privacy flag in +the Protection Database entry for each group named by the -group +argument (use the pts examine command to display the flags): +

If it is the hyphen, only the group's owner and members of the +system:administrators group can add members. +
If it is lowercase a, current members of the group can add new +members. +
If it is uppercase A, anyone who can access the cell's +database server machines can add new members. +

Related Information +

pts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf212.htm b/doc/html/AdminReference/auarf212.htm new file mode 100644 index 0000000..194bc49 --- /dev/null +++ b/doc/html/AdminReference/auarf212.htm @@ -0,0 +1,71 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts apropos

+ + + +

Purpose +

Displays each help entry containing a keyword string +

Synopsis +

pts apropos -topic <help string>  [-help] 
+   
+pts ap -t <help string>  [-h]
+

Description +

The pts apropos command displays the first line of the online +help entry for any pts 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 pts 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 +pts command in which the string specified by the -topic +argument is part of the command name or first line. +

Examples +

The following command lists all pts commands that include the +word create in their names or short descriptions: +

   % pts apropos create
+   creategroup: create a new group
+   createuser: create a new user
+   
+

Privilege Required +

None +

Related Information +

pts +

pts help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf213.htm b/doc/html/AdminReference/auarf213.htm new file mode 100644 index 0000000..da51b69 --- /dev/null +++ b/doc/html/AdminReference/auarf213.htm @@ -0,0 +1,103 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts chown

+ + + + + +

Purpose +

Changes the owner of a Protection Database entry +

Synopsis +

pts chown -name <group name>  -owner <new owner> 
+          [-cell <cell name>]  [-noauth]  [-force]  [-help]
+   
+pts cho -na <group name>  -o <new owner>  [-c <cell name>]  [-no]  [-f]  [-h]
+

Description +

The pts chown command designates the user or group named by the +-owner argument as the owner of the group named by the +-name argument, and records the new owner in the owner field of the +group's Protection Database entry. +

In the case of regular groups, this command automatically changes the group +name's owner prefix (the part of the group name before the colon) to +match the new owner. If the new owner is itself a group, then only its +owner prefix, not its complete name, becomes the owner prefix in the new +name. The change to the owner prefix does not propagate to any groups +owned by the group, however. To make the owner prefix of such +group-owned groups reflect the new owning group, use the pts rename +command. +

It is not possible to change a user or machine entry's owner from the +default set at creation time, the system:administrators +group. +

Cautions +

While designating a machine as a group's owner does not cause an +error, it is not recommended. The Protection Server does not extend the +usual privileges of group ownership to users logged onto the machine. +

Options +

-name +: Specifies the current name of the group to which to assign a new +owner. +
-owner +: Names the user or group to become the group's owner. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example changes the owner of the group +terry:friends from the user terry to the user +pat. A side effect is that the group name changes to +pat:friends. +

   % pts chown -name terry:friends -owner pat
+   
+

The following example changes the owner of the group +terry:friends from the user terry to the group +pat:buddies. A side effect is that the group name +changes to pat:friends. +

   % pts chown -name terry:friends -owner pat:buddies
+   
+

Privilege Required +

The issuer must belong to the system:administrators group +or currently own the group. +

Related Information +

pts +

pts rename +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf214.htm b/doc/html/AdminReference/auarf214.htm new file mode 100644 index 0000000..c2f5e90 --- /dev/null +++ b/doc/html/AdminReference/auarf214.htm @@ -0,0 +1,204 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts creategroup

+ + + + + + + + + + + + + + + + + + + + + + +

Purpose +

Creates an (empty) Protection Database group entry +

Synopsis +

pts creategroup -name <group name>⁺  [-owner <owner of the group>] 
+                [-id <id (negated) for the group>⁺]  [-cell <cell name>]  
+                [-noauth]  [-force]  [-help]
+   
+pts createg -na <group name>⁺  [-o <owner of the group>] 
+            [-i <id (negated) for the group>⁺]  [-c <cell name>]  
+            [-no]  [-f]  [-h]
+      
+pts cg -na <group name>⁺  [-o <owner of the group>]  
+       [-i <id (negated) for the group>⁺]  
+       [-c <cell name>]  [-no]  [-f]  [-h]
+

Description +

The pts creategroup command creates an entry in the Protection +Database for each group specified by the -name argument. The +entry records the issuer of the command as the group's creator, and as +the group's owner unless the -owner argument names an +alternate user or group as the owner. +

There are two types of groups: +

regular, the names of which have two parts separated by a +colon. The part before the colon names the group's owner. +Any user can create such groups. +
prefix-less, which do not have an owner prefix. Only +members of the system:administrators group can create +prefix-less groups. +

Creating a group lowers the issuer's group-creation quota by +one. This is true even if the -owner argument is used to +assign ownership to an alternate user or group. To display a +user's group-creation quota, use the pts examine command; +to set it, use the pts setfields command. +

AFS group ID (AFS GID) numbers are negative integers and by default the +Protection Server assigns a GID that is one less (more negative) than the +current value of the max group id counter in the Protection +Database, decrementing the counter by one for each group. Members of +the system:administrators group can use the -id +argument to assign specific AFS GID numbers. If any of the specified +GIDs is lower (more negative) than the current value of the max group +id counter, the counter is reset to that value. It is acceptable +to specify a GID greater (less negative) than the current value of the +counter, but the creation operation fails if an existing group already has +it. To display or set the value of the max group id counter, +use the pts listmax or pts setmax command, +respectively. +

Output +

The command generates the following string to confirm creation of each +group: +

   group name has id AFS GID
+   
+

Cautions +

Although using the -owner argument to designate a machine entry +as a group's owner does not generate an error, it is not +recommended. The Protection Server does not extend the usual privileges +of group ownership to users logged onto the machine. +

Options +

-name +

Specifies the name of each group to create. Provide a string of up +to 63 characters, which can include lowercase (but not uppercase) letters, +numbers, and punctuation marks. A regular name includes a single colon +(:) to separate the two parts of the name; the colon +cannot appear in a prefix-less group name. +

A regular group's name must have the following format: +

   owner_name:group_name
+   
+

and the owner_name field must reflect the actual owner of the +group, as follows: +

If the optional -owner argument is not included, the field must +match the AFS username under which the issuer is currently +authenticated. +
If the -owner argument names an alternate AFS user, the field +must match that AFS username. +
If the -owner argument names another regular group, the field +must match the owning group's owner field (the part of its name before +the colon). If the -owner argument names a prefix-less +group, the field must match the owning group's complete name. +

-owner +

Specifies a user or group as the owner for each group, rather than the +issuer of the command. Provide either an AFS username or the name of a +regular or prefix-less group. An owning group must already have at +least one member. This requirement prevents assignment of +self-ownership to a group during its creation; use the pts +chown command after issuing this command, if desired. +

-id +

Specifies a negative integer AFS GID number for each group, rather than +allowing the Protection Server to assign it. Precede the integer with a +hyphen (-) to indicate that it is negative. +

If this argument is used and the -name argument names multiple +new groups, it is best to provide an equivalent number of AFS GIDs. The +first GID is assigned to the first group, the second to the second group, and +so on. If there are fewer GIDs than groups, the Protection Server +assigns GIDs to the unmatched groups based on the max group id +counter. If there are more GIDs than groups, the excess GIDs are +ignored. If any of the GIDs is lower (more negative) than the current +value of the max group id counter, the counter is reset to that +value. +

-cell +

Names the cell in which to run the command. For more details, see +the introductory pts reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +

-force +

Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

In the following example, the user pat creates groups called +pat:friends and pat:colleagues. +

   % pts creategroup -name pat:friends pat:colleagues
+   
+

The following example shows a member of the +system:administrators group creating the prefix-less group +staff and assigning its ownership to the +system:administrators group rather than to herself. +

   % pts creategroup -name staff -owner system:administrators
+   
+

In the following example, the user pat creates a group called +smith:team-members, which is allowed because the +-owner argument specifies the required value +(smith). +

   % pts creategroup -name smith:team-members -owner smith
+   
+

Privilege Required +

The issuer must belong to the system:administrators group +to create prefix-less groups or include the -id argument. +

To create a regular group, the issuer must +

Be authenticated. The command fails if the -noauth flag +is provided. +
Have a group-creation quota greater than zero. The pts +examine command displays this quota. +

Related Information +

pts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf215.htm b/doc/html/AdminReference/auarf215.htm new file mode 100644 index 0000000..2f88c36 --- /dev/null +++ b/doc/html/AdminReference/auarf215.htm @@ -0,0 +1,183 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts createuser

+ + + + + + + + + + + + + + + + + + + +

Purpose +

Creates a user or machine entry in the Protection Database +

Synopsis +

pts createuser -name <user name>⁺  [-id <user id>⁺]  [-cell <cell name>]  
+               [-noauth]  [-force]  [-help]
+   
+pts createu -na <user name>⁺  [-i <user id>⁺]  [-c <cell name>]  
+            [-no] [-f]  [-h]
+   
+pts cu -na <user name>⁺  [-i <user id>⁺]  [-c <cell name>]  [-no] [-f]  [-h]
+

Description +

The pts createuser command creates an entry in the Protection +Database for each user or machine specified by the -name +argument. A user entry name becomes the user's AFS username (the +one to provide when authenticating with the AFS Authentication Server). +A machine entry's name is the machine's IP address or a wildcard +notation that represents a range of consecutive IP addresses (a group of +machines on the same network). It is not possible to authenticate as a +machine, but a group to which a machine entry belongs can appear on a +directory's access control list (ACL), thereby granting the indicated +permissions to any user logged on to the machine. +

AFS user IDs (AFS UIDs) are positive integers and by default the Protection +Server assigns an AFS UID that is one greater than the current value of the +max user id counter in the Protection Database, incrementing the +counter by one for each user. To assign a specific AFS UID, use the +-id argument. If any of the specified AFS UIDs is greater +than the current value of the max user id counter, the counter is +reset to that value. It is acceptable to specify an AFS UID smaller +than the current value of the counter, but the creation operation fails if an +existing user or machine entry already has it. To display or set the +value of the max user id counter, use the pts listmax or +pts setmax command, respectively. +

The issuer of the pts createuser command is recorded as the +entry's creator and the group system:administrators as +its owner. +

Cautions +

The Protection Server reserves AFS UID 0 (zero) and returns an error if the +-id argument has that value. +

Options +

-name +

Specifies either a username for a user entry, or an IP address (complete +or wildcarded) for a machine entry: +

A username can include up to 63 numbers and lowercase letters, but it is +best to make it shorter than eight characters, because many application +programs cannot handle longer names. Also, it is best not to include +shell metacharacters or other punctuation marks. In particular, the +colon (:) and at-sign (@) characters are not +acceptable. The period is generally used only in special administrative +names, to separate the username and an instance, as in the example +pat.admin. +
A machine identifier is its IP address in dotted decimal notation (for +example, 192.12.108.240), or a wildcard notation that +represents a set of IP addresses (a group of machines on the same +network). The following are acceptable wildcard formats. The +letters W, X, Y and Z each +represent an actual number from the range 1 through 255. +
- W.X.Y.Z represents a single machine, for +example 192.12.108.240. +
- W.X.Y.0 matches all machines whose IP +addresses start with the first three numbers. For example, +192.12.108.0 matches both +192.12.108.119 and +192.12.108.120, but does not match +192.12.105.144. +
- W.X.0.0 matches all machines whose IP +addresses start with the first two numbers. For example, the address +192.12.0.0 matches both +192.12.106.23 and +192.12.108.120, but does not match +192.5.30.95. +
- W.0.0.0 matches all machines whose IP +addresses start with the first number in the specified address. For +example, the address 192.0.0.0 matches both +192.5.30.95 and +192.12.108.120, but does not match +138.255.63.52. +
+
Do not define a machine entry with the name +0.0.0.0 to match every machine. The +system:anyuser group is equivalent. +

-id +

Specifies an AFS UID for each user or machine entry, rather than allowing +the Protection Server to assign it. Provide a positive integer. +

If this argument is used and the -name argument names multiple +new entries, it is best to provide an equivalent number of AFS UIDs. +The first UID is assigned to the first entry, the second to the second entry, +and so on. If there are fewer UIDs than entries, the Protection Server +assigns UIDs to the unmatched entries based on the max user id +counter. If there are more UIDs than entries, the excess UIDs are +ignored. If any of the UIDs is greater than the current value of the +max user id counter, the counter is reset to that value. +

-cell +

Names the cell in which to run the command. For more details, see +the introductory pts reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +

-force +

Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The command generates the following string to confirm creation of each +user: +

   User name has id id
+   
+

Examples +

The following example creates a Protection Database entry for the user +johnson. +

   % pts createuser -name johnson
+   
+

The following example creates three wildcarded machine entries in the ABC +Corporation cell. The three entries encompass all of the machines on +the company's networks without including machines on other +networks: +

   % pts createuser -name 138.255.0.0 192.12.105.0 192.12.106.0
+   
+

Privilege Required +

The issuer must belong to the system:administrators +group. +

Related Information +

pts +

pts listmax +

pts setmax +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf216.htm b/doc/html/AdminReference/auarf216.htm new file mode 100644 index 0000000..f57bcf3 --- /dev/null +++ b/doc/html/AdminReference/auarf216.htm @@ -0,0 +1,107 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts delete

+ + + + + + + + + + +

Purpose +

Deletes a Protection Database entry +

Synopsis +

pts delete -nameorid <user or group name or id>⁺  [-cell <cell name>]  
+           [-noauth]  [-force]  [-help]
+   
+pts d -na <user or group name or id>⁺  [-c <cell name>]  [-no]  [-f]  [-h]
+

Description +

The pts delete command removes each entry specified by the +-nameorid argument from the Protection Database. Deleting +entries affects other parts of the system in various ways: +

Deleted users and groups still appear on access control lists (ACLs), but +are listed by AFS UID or GID rather than by name, because there is no longer +an associated name to which to translate the ID. To remove these +obsolete entries from ACLs, use the fs cleanacl command. +
Deleting a user or machine's entry removes it from the membership +list of any group to which it belonged. +
Deleting a group entry removes it from the membership list of any user or +machine entry that belonged to the group, and also increments the +group-creation quota of the group's creator by one, even if the creator +no longer owns the group. +

To remove a user or machine from a group without actually deleting the +entry, use the pts removeuser command. +

Options +

-nameorid +: Specifies the name or AFS UID of each user, the name or AFS GID of each +group, or the IP address (complete or wildcard-style) or AFS UID of each +machine entry to delete. It is acceptable to mix users, machines, and +groups on the same command line, as well as names (IP addresses for machines) +and IDs. Precede the GID of each group with a hyphen to indicate that +it is negative. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example deletes the user entries pat and +terry: +

   % pts delete pat terry
+   
+

The following example deletes the Protection Database entry of the group +with AFS GID -215. +

   % pts delete -215
+   
+

Privilege Required +

The issuer must belong to the system:administrators group +to delete user and machine entries. To delete group entries, the issuer +must either own the group or belong to the +system:administrators group. +

Related Information +

fs cleanacl +

pts +

pts removeuser +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf217.htm b/doc/html/AdminReference/auarf217.htm new file mode 100644 index 0000000..c9d3307 --- /dev/null +++ b/doc/html/AdminReference/auarf217.htm @@ -0,0 +1,256 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts examine

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Purpose +

Displays a Protection Database entry +

Synopsis +

pts examine -nameorid <user or group name or id>⁺  [-cell <cell name>]   
+            [-noauth]  [-force]  [-help]
+    
+pts e -na <user or group name or id>⁺  [-c <cell name>]  [-no]  [-f]  [-h]
+   
+pts check -na <user or group name or id>⁺  [-c <cell name>]  
+          [-no]  [-f]  [-h]
+   
+pts che -na <user or group name or id>⁺  [-c <cell name>]  
+        [-no]  [-f]  [-h]
+

Description +

The pts examine command displays information from the Protection +Database entry of each user, machine or group specified by the +-nameorid argument. +

Options +

-nameorid +: Specifies the name or AFS UID of each user, the name or AFS GID of each +group, or the IP address (complete or wildcard-style) or AFS UID of each +machine for which to display the Protection Database entry. It is +acceptable to mix users, machines, and groups on the same command line, as +well as names (IP addresses for machines) and IDs. Precede the GID of +each group with a hyphen to indicate that it is negative. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output for each entry consists of two lines that include the following +fields: +

Name +

The contents of this field depend on the type of entry: +

For a user entry, it is the username that the user types when +authenticating with AFS. +
For a machine entry, it is either the IP address of a single machine in +dotted decimal format, or a wildcard notation that represents a group of +machines on the same network. See the pts createuser +reference page for an explanation of the wildcard notation. +
For a group entry, it is one of two types of group name. If the +name has a colon between the two parts, it represents a regular group and the +part before the prefix reflects the group's owner. A prefix-less +group does not have the owner field or the colon. For more details on +group names, see the pts creategroup reference page. +

+ + + +

id +

A unique number that the AFS server processes use to identify AFS users, +machines and groups. AFS UIDs for user and machine entries are positive +integers, and AFS GIDs for group entries are negative integers. AFS +UIDs and GIDs are similar in function to the UIDs and GIDs used in local file +systems such as UFS, but apply only to AFS operations. + + +

owner +

The user or group that owns the entry and thus can administer it (change +the values in most of the fields displayed in the output of this command), or +delete it entirely. The Protection Server automatically records the +system:administrators group in this field for user and +machine entries at creation time. + +

creator +

The user who issued the pts createuser or pts +creategroup command to create the entry. This field serves as an +audit trail, and cannot be changed. + +

membership +

An integer that for users and machines represents the number of groups to +which the user or machine belongs. For groups, it represents the number +of group members. +

flags +

A string of five characters, referred to as privacy flags, +which indicate who can display or administer certain aspects of the +entry. +

s +: Controls who can issue the pts examine command to display the +entry. +
o +: Controls who can issue the pts listowned command to display the +groups that a user or group owns. +
m +: Controls who can issue the pts membership command to display +the groups a user or machine belongs to, or which users or machines belong to +a group. +
a +: Controls who can issue the pts adduser command to add a user or +machine to a group. It is meaningful only for groups, but a value must +always be set for it even on user and machine entries. +
r +: Controls who can issue the pts removeuser command to remove a +user or machine from a group. It is meaningful only for groups, but a +value must always be set for it even on user and machine entries. +

Each flag can take three possible types of values to enable a different set +of users to issue the corresponding command: +

A hyphen (-) designates the members of the +system:administrators group and the entry's +owner. For user entries, it designates the user in addition. +
The lowercase version of the letter applies meaningfully to groups only, +and designates members of the group in addition to the individuals designated +by the hyphen. +
The uppercase version of the letter designates everyone. +

group quota +

The number of additional groups the user is allowed to create. The +pts createuser command sets it to 20 for both users and machines, +but it has no meaningful interpretation for a machine, because it is not +possible to authenticate as a machine. Similarly, it has no meaning in +group entries and the pts creategroup command sets it to 0 +(zero); do not change this value. + + +

Examples +

The following example displays the user entry for terry and the +machine entry 158.12.105.44. +

   % pts examine terry 158.12.105.44
+   Name: terry, id: 1045, owner: system:administrators, creator: admin, 
+     membership: 9, flags: S----, group quota: 15.
+   Name: 158.12.105.44, id: 5151, owner: system:administrators, 
+     creator: byu, membership: 1, flags: S----, group quota: 20.
+   
+

The following example displays the entries for the AFS groups with GIDs +-673 and -674. +

   % pts examine -673 -674
+   Name: terry:friends, id: -673, owner: terry, creator: terry, 
+     membership: 5, flags: S-M--, group quota: 0.
+   Name: smith:colleagues, id: -674, owner: smith, creator: smith, 
+     membership: 14, flags: SOM--, group quota: 0.
+   
+

Privilege Required +

The required privilege depends on the setting of the first privacy flag in +the Protection Database entry of each entry specified by the +-nameorid argument: +

If it is lowercase s, members of the +system:administrators group and the user associated with a +user entry can examine it, and only members of the +system:administrators group can examine a machine or group +entry. +
If it is uppercase S, anyone who can access the cell's +database server machines can examine the entry. +

Related Information +

pts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf218.htm b/doc/html/AdminReference/auarf218.htm new file mode 100644 index 0000000..755674d --- /dev/null +++ b/doc/html/AdminReference/auarf218.htm @@ -0,0 +1,85 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts help

+ + + +

Purpose +

Displays the syntax of specified pts commands or lists +functional descriptions for all pts commands +

Synopsis +

pts help [-topic <help string>⁺]  [-help]
+    
+pts h [-t <help string>⁺]  [-h]
+

Description +

The pts help command displays the complete online help entry +(short description and syntax statement) for each command operation code +specified by the -topic argument. If the -topic +argument is omitted, the output includes the first line (name and short +description) of the online help entry for every pts command. +

To list every pts command whose name or short description +includes a specified keyword, use the pts apropos command. +

Options +

-topic +: Indicates each command for which to display the complete online help +entry. Omit the pts part of the command name, providing only +the operation code (for example, specify membership, not pts +membership). If this argument is omitted, the output briefly +describes every pts command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each pts command consists of the +following two or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following command displays the online help entry for the pts +membership command: +

   % pts help membership
+   pts membership:  list membership of a user or group
+   aliases: groups
+   Usage: pts membership -nameorid <user or group name or id>+ 
+   [-cell <cell name>] [-noauth] [-force] [-help]
+   
+

Privilege Required +

None +

Related Information +

pts +

pts apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf219.htm b/doc/html/AdminReference/auarf219.htm new file mode 100644 index 0000000..74df121 --- /dev/null +++ b/doc/html/AdminReference/auarf219.htm @@ -0,0 +1,112 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts listentries

+ + + + + + +

Purpose +

Displays all user or group entries in the Protection Database +

Synopsis +

pts listentries [-users]  [-groups]  [-cell <cell name>]
+                [-noauth]  [-force]  [-help]
+   
+pts liste [-u]  [-g]  [-c <cell name>]  [-n]  [-f]  [-h]
+

Description +

The pts listentries command displays the name and AFS ID of all +Protection Database entries of the indicated type. It also displays the +AFS ID of each entry's owner and creator. +

To display all user and machine entries, either include the +-users flag or omit both it and the -groups flag. +To display all group entries, include the -groups flag. To +display all entries, provide both flags. +

Options +

-users +: Displays user and machine entries. +
-groups +: Displays group entries. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output includes a line for each entry, with information in four columns +that have the following headers: +

Name +: The entry's name +
ID +: The entry's AFS ID (AFS UID for a user or machine, negative AFS GID +for a group) +
Owner +: The AFS ID of the user or group that owns the entry +
Creator +: The AFS ID of the user who created the entry (the +system:administrators group is listed as the creator of the +entry for anonymous and the system groups, but it is not otherwise +possible for a group to create groups) +

In general, the entries appear in the order in which they were +created. +

Examples +

The following example displays both user and group entries. +

   % pts listentries -users -groups
+   Name                          ID  Owner Creator
+   system:administrators       -204   -204    -204 
+   system:anyuser              -101   -204    -204 
+   system:authuser             -102   -204    -204 
+   anonymous                  32766   -204    -204 
+   admin                          1   -204   32766 
+   pat                          100   -204       1 
+   smith                        101   -204       1 
+   pat:friends                 -206    100     100 
+   staff                       -207   -204       1
+   
+

Privilege Required +

The issuer must belong to the system:administrators +group. +

Related Information +

pts +

pts creategroup +

pts createuser +

pts examine +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf220.htm b/doc/html/AdminReference/auarf220.htm new file mode 100644 index 0000000..6f8c351 --- /dev/null +++ b/doc/html/AdminReference/auarf220.htm @@ -0,0 +1,90 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts listmax

+ + + + + + + + +

Purpose +

Displays the max user id and max group id counters +

Synopsis +

pts listmax [-cell <cell name>]  [-noauth]  [-force]  [-help]
+    
+pts listm  [-c <cell name>]  [-n]  [-f]  [-h]
+

Description +

The pts listmax command displays the values of the max user +id and max group id counters, which the Protection Server +uses to track the AFS user IDs (AFS UIDs) it allocates to new users or +machines, and the AFS group IDs (AFS GIDs) it allocates to new groups, +respectively. When an administrator next issues the pts +createuser command and does not include the -id argument, the +new user or machine receives an AFS UID one greater than the max user +id counter, and when a user issues the pts creategroup +command and does not include the -id argument, the new group +receives an AFS UID one less (more negative) than the max group id +counter. +

To reset one or both counters, members of the +system:administrators group can issue the pts +setmax command. +

Options +

-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The command displays the counters in the following format: +

   Max user id is user_counter and max group id is group_counter.
+   
+

Examples +

The following example displays the output of this command: +

   % pts listmax
+   Max user name is 1271 and max group id is -382.
+   
+

Privilege Required +

None +

Related Information +

pts +

pts setmax +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf221.htm b/doc/html/AdminReference/auarf221.htm new file mode 100644 index 0000000..db060e2 --- /dev/null +++ b/doc/html/AdminReference/auarf221.htm @@ -0,0 +1,127 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts listowned

+ + + + + + + +

Purpose +

Displays the Protection Database groups owned by a user or group +

Synopsis +

pts listowned -nameorid <user or group name or id>⁺  [-cell <cell name>]  
+              [-noauth]  [-force]  [-help]
+   
+pts listo -na <user or group name or id>⁺  [-c <cell name>]  
+          [-no]  [-f]  [-h]
+

Description +

The pts listowned command lists the groups owned by each user or +group specified by the -nameorid argument. +

To list any orphaned groups, whose owners have themselves been +deleted from the Protection Database, provide a value of 0 (zero) +for the -nameorid argument. To change the owner to a user or +group that still exists, use the pts chown command. +

Options +

-nameorid +

Specifies the name or AFS UID of each user, or the name or AFS GID of each +group, for which to display the list of owned groups. It is acceptable +to mix users and groups on the same command line, as well as names and +IDs. Precede the GID of each group with a hyphen to indicate that it is +negative. +

A value of 0 (zero) lists group entries for groups whose owners +no longer have entries in the Protection Database. +

-cell +

Names the cell in which to run the command. For more details, see +the introductory pts reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +

-force +

Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The first line of the output indicates the name and AFS UID or AFS GID of +each user or group for which ownership information is requested, in the +following format: +

   Groups owned by name (id: ID) are:
+   
+

A list of groups follows. The list does not include groups owned by +groups that the user or group owns, or to which the user or group +belongs. If the user or group does not own any groups, only the header +line appears. +

The following error message appears if the issuer is not privileged to view +ownership information. By default, for both user and group entries the +second privacy flag is the hyphen, which denies permission to anyone other +than the user (for a user entry) and the members of the +system:administrators group. +

   pts: Permission denied so failed to get owner list for name (id: ID)
+   
+

Examples +

The following example lists the groups owned by user terry and +shows that the group terry:friends does not own any +groups: +

   % pts listowned terry terry:friends
+   Groups owned by terry (id: 1045) are:
+     terry:friends
+     terry:project1
+     terry:project2
+   Groups owned by terry:friends (id: -673) are:
+   
+

Privilege Required +

The required privilege depends on the setting of the second privacy flag in +the Protection Database entry of each user or group indicated by the +-nameorid argument (use the pts examine command to +display the flags): +

If it is the hyphen and the -nameorid argument specifies a +group, only the members of the system:administrators group +and the owner of a group can list the groups it owns. +
If it is the hyphen and the -nameorid argument specifies a +user, only the members of the system:administrators group and +the associated user can list the groups he or she owns. +
If it is uppercase letter O, anyone who can access the +cell's database server machines can list the groups owned by this user or +group. +

Related Information +

pts +

pts chown +

pts examine +

pts setfields +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf222.htm b/doc/html/AdminReference/auarf222.htm new file mode 100644 index 0000000..c09c79f --- /dev/null +++ b/doc/html/AdminReference/auarf222.htm @@ -0,0 +1,146 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts membership

+ + + + + + + + +

Purpose +

Displays the membership list for a user or group +

Synopsis +

pts membership -nameorid <user or group name or id>⁺  [-cell <cell name>]  
+               [-noauth]  [-force]  [-help]
+   
+pts m -na <user or group name or id>⁺  [-c <cell name>]  [-no]  [-f]  [-h]
+   
+pts groups -na <user or group name or id>⁺  [-c <cell name>]
+           [-no] [-f]  [-h]
+   
+pts g -na <user or group name or id>⁺  [-c <cell name>]  [-no]  [-f]  [-h]
+

Description +

The pts membership command lists the groups to which each user +or machine specified by the -nameorid argument belongs, or lists +the users and machines that belong to each group specified by the +-nameorid argument. +

It is not possible to list the members of the +system:anyuser or system:authuser groups, +and they do not appear in the list of groups to which a user belongs. +

To add users or machine to groups, use the pts adduser +command; to remove them, use the pts removeuser +command. +

Options +

-nameorid +: Specifies the name or AFS UID of each user entry, the IP address (complete +or wildcard-style) or AFS UID of each machine entry, or the name or AFS GID of +each group, for which to list group membership. It is acceptable to mix +users, machines, and groups on the same command line, as well as names and +IDs. Precede the GID of each group with a hyphen to indicate that it is +negative. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

For each user and machine, the output begins with the following header +line, followed by a list of the groups to which the user or machine +belongs: +

   Groups name (id: AFS UID) is a member of:
+   
+

For each group, the output begins with the following header line, followed +by a list of the users and machines who belong to the group: +

   Members of group_name (id: AFS GID) are:
+   
+

Examples +

The following example lists the groups to which the user pat +belongs and the members of the group smith:friends. +Note that third privacy flag for the pat entry was changed from the +default hyphen to enable a non-administrative user to obtain this +listing. +

   % pts membership pat smith:friends
+   Groups pat (id: 1144) is a member of:
+     smith:friends
+     staff
+     johnson:project-team
+   Members of smith:friends (id: -562) are:
+     pat
+     terry
+     jones
+     richard
+     thompson
+   
+

Privilege Required +

The required privilege depends on the setting of the third privacy flag in +the Protection Database entry of each user or group indicated by the +-nameorid argument (use the pts examine command to +display the flags): +

If it is the hyphen and the -nameorid argument specifies a +user, only the associated user and members of the +system:administrators group can list the groups to which the +user belongs. +
If it is the hyphen and the -nameorid argument specifies a +machine, only the members of the system:administrators group +can list the groups to which the machine belongs. +
If it is the hyphen and the -nameorid argument specifies a +group, only the owner of the group and members of the +system:administrators group can list the members of the +group. +
If it is lowercase m and the -nameorid argument +specifies a user or machine entry, the meaning is equivalent to the +hyphen. +
If it is lowercase m and the -nameorid argument +specifies a group, members of the group can also list the other +members. +
If it is uppercase M, anyone who can access the cell's +database server machines can list group memberships. +

Related Information +

pts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf223.htm b/doc/html/AdminReference/auarf223.htm new file mode 100644 index 0000000..9d25b70 --- /dev/null +++ b/doc/html/AdminReference/auarf223.htm @@ -0,0 +1,111 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts removeuser

+ + + + + + + + +

Purpose +

Removes a user from a Protection Database group +

Synopsis +

pts removeuser -user <user name>⁺  -group <group name>⁺
+               [-cell <cell name>]  [-noauth]  [-force]  [-help]
+   
+pts rem -u <user name>⁺  -g <group name>⁺  [-c <cell name>]  
+        [-n]  [-f]  [-h]
+

Description +

The pts removeuser command removes each user or machine named by +the -user argument from each group named by the -group +argument. +

To add users to a group, use the pts adduser command. To +list group membership, use the pts membership command. To +remove users from a group and delete the group's entry completely in a +single step, use the pts delete command. +

Cautions +

AFS compiles each user's group membership as he or she +authenticates. Any users who have valid tokens when they are removed +from a group retain the privileges extended to that group's members until +they discard their tokens or reauthenticate. +

Options +

-name +: Specifies the name of each user entry or the IP address (complete or +wildcard-style) of each machine entry to remove. +
-group +: Names each group from which to remove members. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example removes user smith from the groups +staff and staff:finance. Note that no +switch names are necessary because only a single instance is provided for the +first argument (the username). +

   % pts removeuser smith staff staff:finance
+   
+

The following example removes three machine entries, which represent all +machines in the ABC Corporation network, from the group +bin-prot: +

   % pts removeuser -user 138.255.0.0 192.12.105.0 192.12.106.0 -group bin-prot
+   
+

Privilege Required +

The required privilege depends on the setting of the fifth privacy flag in +the Protection Database for the group named by the -group argument +(use the pts examine command to display the flags): +

If it is the hyphen, only the group's owner and members of the +system:administrators group can remove members. +
If it is lowercase r, members of the group can also remove +other members. +

(It is not possible to set the fifth flag to uppercase +R.) +

Related Information +

pts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf224.htm b/doc/html/AdminReference/auarf224.htm new file mode 100644 index 0000000..56eb0dc --- /dev/null +++ b/doc/html/AdminReference/auarf224.htm @@ -0,0 +1,110 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts rename

+ + + + + + +

Purpose +

Changes the name of a Protection Database entry +

Synopsis +

pts rename -oldname <old name>  -newname <new name>
+           [-cell <cell name>]  [-noauth]  [-force]  [-help]
+    
+pts ren -o <old name>  -ne <new name>  [-c <cell name>]  [-no]  [-f]  [-h]
+

Description +

The pts rename command changes the name of the user, machine, or +group entry specified by the -oldname argument to the name +specified by the -newname argument. It is not possible to +change a user or machine entry's name to look like a regular group +entry's name (have a colon in it). +

Members of the system:administrators group can change a +regular group name into a prefix-less name and vice versa. When +changing a prefix-less group name into a regular group name or a regular group +name to another regular group name, the owner field of the new name (the part +before the colon) must correctly reflect the group's owner. +

Changing a regular group's owner with the pts chown command +automatically changes the owner field (the part before the colon) of the +group's name, but does not change the owner field of any groups owned by +the group. Use this command to rename those groups to a form that +accurately reflects their ownership. +

Cautions +

By convention, many aspects of an AFS user account have the same name as +the user's Protection Database entry, including the Authentication +Database entry, volume, and mount point. When using this command to +change a user name, also change the names of all related entities to maintain +consistency. For instructions, see the chapter on user accounts in the +IBM AFS Administration Guide. +

Options +

-oldname +: Specifies the current full name of the entry. +
-newname +: Specifies the new full name for the entry. For regular groups, the +owner field (the part before the colon) of the new name must reflect the +actual ownership of the group. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example changes the name of the group staff, owned +by the privileged user admin, to +admin:staff: +

   % pts rename -oldname staff -newname admin:staff
+   
+

The following example changes the name of the group +admin:finance to the group finance. The +issuer must belong to the system:administrators group. +

   % pts rename -oldname admin:finance -newname finance
+   
+

Privilege Required +

To change a regular group name to a prefix-less name or vice versa, or to +change a user or machine entry's name, the issuer must belong to the +system:administrators group. +

To change a group name to a new name of the same type (regular or +prefix-less), the issuer must own the group or belong to the +system:administrators group. +

Related Information +

pts +

pts chown +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf225.htm b/doc/html/AdminReference/auarf225.htm new file mode 100644 index 0000000..2e35f6f --- /dev/null +++ b/doc/html/AdminReference/auarf225.htm @@ -0,0 +1,199 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts setfields

+ + + + + + + + + + + + + +

Purpose +

Sets privacy flags or the group-creation quota for a Protection Database +entry. +

Synopsis +

pts setfields -nameorid <user or group name or id>⁺
+              [-access <set privacy flags>]
+              [-groupquota <set limit on group creation>]
+              [-cell <cell name>]  [-noauth]  [-force]  [-help]
+   
+pts setf -na <user or group name or id>⁺  [-a <set privacy flags>] 
+         [-g <set limit on group creation>]  [-c <cell name>] 
+         [-no]  [-f]  [-h]
+

Description +

The pts setfields command sets the group-creation quota, the +privacy flags, or both, associated with each user, machine, or group entry +specified by the -nameorid argument. +

To examine the current quota and privacy flags, use the pts +examine command. +

Cautions +

Changing a machine or group's group-creation quota is allowed, but not +recommended. The concept is meaningless for machines and groups, +because it is impossible to authenticate as a group or machine. +

Similarly, some privacy flag settings do not have a sensible +interpretation. The Arguments section specifies the +appropriate settings. +

Options +

-nameorid +

Specifies the name or AFS UID of each user, the IP address (complete or +wildcard-style) of each machine, or the name or AFS GID of each machine for +which to set privacy flags or group-creation quota. It is acceptable to +mix users, machines, and groups on the same command line, as well as names (IP +addresses for machines) and IDs. Precede the GID of each group with a +hyphen to indicate that it is negative. +

-access +

Specifies the privacy flags to apply to each entry. Provide a +string of five characters, one for each of the permissions. If this +option is omitted, the current setting remains unchanged. +

Set each flag to achieve the desired combination of permissions. If +the following list does not mention a certain setting, it is not +acceptable. For further discussion of the privacy flags, see the +pts examine reference page. +

The first flag determines who can use the pts examine command +to display information from a user, machine or group's Protection +Database entry. +
- Set it to lowercase s to permit the members of the +system:administrators group to display a user, machine, or +group entry, and the associated user to display a user entry. +
- Set it to uppercase S to permit anyone who can access the +cell's database server machines to display a user, machine, or group +entry. +
+
The second flag determines who can use the pts listowned +command to list the groups that a user or group owns. +
- Set it to the hyphen (-) to permit the members of the +system:administrators group and a user to list the groups he +or she owns, or to permit the members of the +system:administrators group and a group's owner to list +the groups that a group owns. +
- Set it to uppercase letter O to permit anyone who can access +the cell's database server machines to list the groups owned by a machine +or group entry. +
+
The third flag determines who can use the pts membership +command to list the groups to which a user or machine belongs, or the users +and machines that belong to a group. +
- Set it to the hyphen (-) to permit the members of the +system:administrators group and a user to list the groups he +or she belongs to, to permit the members of the +system:administrators group to list the groups a machine +belongs to, or to permit the members of the +system:administrators group and a group's owner to list +the users and machines that belong to it. +
- Set it to lowercase m to permit members of a group to list the +other members. (For user and machine entries, this setting is +equivalent to the hyphen.) +
- Set it to uppercase M to permit anyone who can access the +cell's database server machines to list membership information for a +user, machine or group. +
+
The fourth flag determines who can use the pts adduser command +to add users and machines as members of a group. This flag has no +sensible interpretation for user and machine entries, but must be set +nonetheless, preferably to the hyphen. +
- Set it to the hyphen (-) to permit the members of the +system:administrators group and the owner of the group to add +members. +
- Set it to lowercase a to permit members of a group to add other +members. +
- Set it to uppercase A to permit anyone who can access the +cell's database server machines to add members to a group. +
+
The fifth flag determines who can use the pts removeuser +command to remove users and machines from membership in a group. This +flag has no sensible interpretation for user and machine entries, but must be +set nonetheless, preferably to the hyphen. +
- Set it to the hyphen (-) to permit the members of the +system:administrators group and the owner of the group to +remove members. +
- Set it to lowercase r to permit members of a group to remove +other members. +
+

-groupquota +

Specifies the number of additional groups a user can create (it does not +matter how many he or she has created already). Do not include this +argument for a group or machine entry. +

-cell +

Names the cell in which to run the command. For more details, see +the introductory pts reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +

-force +

Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example changes the privacy flags on the group +operators, retaining the default values of the first, second and +third flags, but setting the fourth and fifth flags to enable the group's +members to add and remove other members. +

   % pts setfields -nameorid operators -access S-Mar
+   
+

The following example changes the privacy flags and sets group quota on the +user entry admin. It retains the default values of the +first, fourth, and fifth flags, but sets the second and third flags, to enable +anyone to list the groups that admin owns and belongs to. +Users authenticated as admin can create an additional 50 +groups. +

   % pts setfields -nameorid admin -access SOM-- -groupquota 50
+   
+

Privilege Required +

To edit group entries or set the privacy flags on any type of entry, the +issuer must own the entry or belong to the +system:administrators group. To set group-creation +quota on a user entry, the issuer must belong to the +system:administrators group. +

Related Information +

pts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf226.htm b/doc/html/AdminReference/auarf226.htm new file mode 100644 index 0000000..a7ddf74 --- /dev/null +++ b/doc/html/AdminReference/auarf226.htm @@ -0,0 +1,95 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

pts setmax

+ + + + + + + + +

Purpose +

Sets the value of the max group id or max user id +counter +

Synopsis +

pts setmax [-group <group max>]  [-user <user max>]  [-cell <cell name>]   
+           [-noauth]  [-force]  [-help] 
+    
+pts setm [-g group max>]  [-u <user max>]  [-c <cell name>]  [-n]  [-f]  [-h]
+

Description +

The pts setmax command sets the value of one or both counters +that track the IDs the Protection Server allocates to new users, machines, or +groups: the max user id counter for the AFS user IDs (AFS +UIDs) assigned to users and machines, and the max group id counter +for the AFS group IDs (AFS GIDs) assigned to groups. +

Use the pts listmax command to display the current value of both +counters. +

Options +

-group +: Sets the max group id counter. Precede the value with a +hyphen to indicate that it is negative. When an administrator next uses +the pts creategroup command to create a group entry and does not +include that command's -id argument, the Protection Server +assigns the group an AFS GID one less (more negative) than this value. +
-user +: Sets the max user id counter. When an administrator next +uses the pts createuser command to create a user or machine entry +and does not include that command's -id argument, the +Protection Server assigns the group an AFS UID one greater than this +value. +
-cell +: Names the cell in which to run the command. For more details, see +the introductory pts reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. For more details, see the introductory pts reference +page. +
-force +: Enables the command to continue executing as far as possible when errors +or other problems occur, rather than halting execution at the first +error. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command sets the max group id counter to -500 and +the max user id counter to 1000. +

   % pts setmax -group -500 -user 1000
+   
+

Privilege Required +

The issuer must belong to the system:administrators +group. +

Related Information +

pts +

pts creategroup +

pts createuser +

pts listmax +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf227.htm b/doc/html/AdminReference/auarf227.htm new file mode 100644 index 0000000..e9cedcf --- /dev/null +++ b/doc/html/AdminReference/auarf227.htm @@ -0,0 +1,114 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

ptserver

+ + + + + +

Purpose +

Initializes the Protection Server +

Synopsis +

ptserver [-database <db path>]  [-p <number of processes>] [-rebuildDB] 
+         [-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 ptserver command initializes the Protection Server, which +must run on every database server machine. In the conventional +configuration, its binary file is located in the /usr/afs/bin +directory on a file server machine. +

The ptserver command is not normally issued at the command shell +prompt, but rather placed into a database server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a file server machine as the local superuser +root. +

The Protection Server performs the following tasks: +

Maintains the Protection Database, which contains entries for every user +and group in the cell. Use the pts commands to administer +the database. +
Allocates AFS IDs for new user, machine and group entries and maps each ID +to the corresponding name. +
Generates a current protection subgroup (CPS) at the File Server's +request. The CPS lists all groups to which a user or machine +belongs. +

Options +

-database +: Specifies the pathname of an alternate directory in which the Protection +Database files reside. Provide the complete pathname, ending in the +base filename to which the .DB0 and +.DBSYS1 extensions are appended. For example, the +appropriate value for the default database files is +/usr/afs/db/prdb. +
-p +: Sets the number of server lightweight processes (LWPs) to run. +Provide a positive integer from the range 3 to +16. The default value is 3. +
-rebuildDB +: Rebuilds the Protection Database at the beginning of Protection Server +initialization. Use this argument only in consultation with AFS +Development or Product Support. +
-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 following bos create command creates a ptserver +process on the machine fs3.abc.com. The +command appears here on multiple lines only for legibility. +

   % bos create -server fs3.abc.com -instance ptserver  \
+                -type simple -cmd /usr/afs/bin/ptserver
+   
+

Privilege Required +

Related Information +

pts +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf228.htm b/doc/html/AdminReference/auarf228.htm new file mode 100644 index 0000000..99a4d51 --- /dev/null +++ b/doc/html/AdminReference/auarf228.htm @@ -0,0 +1,120 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

rcp (AFS version)

+ + + + + + +

Purpose +

Copies a file on a remote machine +

Synopsis +

rcp [-p]  <file1>  <file2>
+   
+rcp [-r]  [-p]  <file>⁺  <directory>
+

Description +

The AFS-modified rcp program functions like the standard UNIX +rcp program, but also passes the issuer's AFS token to the +remote machine's Cache Manager, to enable authenticated access to the AFS +filespace via that machine. +

Token passing is most effective if both the remote machine and local +machine belong to the same cell, because the rcp command can pass +only one token even if the user has several tokens--it passes the token +listed first in the output from the tokens command. If the +remote and local machine do not belong to the same cell, the possibilities are +as follows: +

The passed token is for the remote machine's cell. The issuer +accesses the remote cell's AFS file tree as an authenticated AFS user, +but is considered anonymous in the local cell and so can exercise +only the access rights granted to the system:anyuser group +there. For example, to copy a file into a local AFS directory from the +remote cell, the directory's ACL must grant the l +(lookup) and i (insert) permissions to the +system:anyuser group. +
The passed token is for the local machine's cell. The issuer +accesses the remote cell's AFS file tree as anonymous, and so +can only exercise the access rights granted to the +system:anyuser group. +

In addition to running the AFS version of the rcp binary on the +machine where the rcp command is issued, other configuration +changes are necessary for token passing to work properly. See the +Cautions section for a list. +

The AFS version of the rcp command is compatible with the +standard inetd command, but token passing works only if both +programs are modified to handle AFS tokens. If only one of them is +modified, the issuer accesses the AFS filespace through the remote machine as +the anonymous user. +

Cautions +

The AFS distribution does not include an AFS-modified version of this +command for every system type, in some cases because the operating system +vendor has already modified the standard version in the required way. +For details, see the IBM AFS Release Notes. +

The AFS rcp command does not allow third party copies, in which +neither the source file nor the target file is stored on the machine where the +command is issued. The standard UNIX rcp command claims to +provide this functionality. +

For security's sake, use the AFS version of the rcp command +only in conjunction with PAGs, either by using an AFS-modified login utility, +issuing the pagsh command before obtaining tokens, or including the +-setpag flag to the klog command. +

Several configuration requirements and restrictions are necessary for token +passing to work correctly with an AFS-modified version of the rcp +command. Some of these are also necessary with the standard UNIX +version, but are included here because the issuer accustomed to AFS +protections is possibly unlikely to consider them. There are possibly +other UNIX-based requirements and restrictions not mentioned here; +consult the UNIX manual page. (One important one is that no +stty commands can appear in the issuer's shell initialization +file, such as the .cshrc file.) +

The requirements and restrictions for token passing include the +following. +

The local machine must be running the AFS version of the rcp +command, with the rcp binary file locally installed to grant setuid +privilege to the owner, the local superuser root. +
The remote machine must be running the AFS version of the inetd +program. +
If the rcp command is to consult a .rhosts +file on the remote machine, the file must have UNIX protections no more +liberal than -rw-r--r--. If the .rhosts +file resides in a user home directory in AFS, the home directory must also +grant the lookup (l) and read (r) +permissions to the system:anyuser group. +

Options +

Consult the UNIX manual page for the rcp command. +

Privilege Required +

None +

Related Information +

UNIX manual page for rcp +

IBM AFS Release Notes +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf229.htm b/doc/html/AdminReference/auarf229.htm new file mode 100644 index 0000000..72edd98 --- /dev/null +++ b/doc/html/AdminReference/auarf229.htm @@ -0,0 +1,105 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

rsh (AFS version)

+ + + + + +

Purpose +

Opens a shell on a remote machine +

Synopsis +

rsh host  [-n]  [-l <username>]  <command>
+   
+host  [-n]  [-l <username>]    <command>
+

Description +

The AFS-modified rsh program functions like the standard UNIX +rsh program, but also passes the issuer's AFS token to the +remote machine's Cache Manager, to enable authenticated access to the AFS +filespace via that machine. +

Token passing is most effective if both the remote machine and local +machine belong to the same cell, because the rsh program can pass +only one token even if the user has several tokens--it passes the token +listed first in the output from the tokens command. If the +remote and local machine do not belong to the same cell, the first token must +be valid for the remote machine's cell, in order for the remote +cell's server processes to recognize the issuer as authenticated. +

In addition to running the AFS version of the rsh binary on the +machine where the rsh command is issued, other configuration +changes are necessary for token passing to work properly. See the +Cautions section for a list. +

The AFS version of the rsh command is compatible with the +standard UNIX inetd command, but token passing works only if both +programs are modified to handle AFS tokens. If only one of them is +modified, the issuer accesses the AFS filespace through the remote machine as +the user anonymous. +

Cautions +

Some operating systems assign an alternate name to this program, such as +remsh. The version included in the AFS distribution uses the +same name as the operating system. +

For security's sake, use the AFS version of the rsh command +only in conjunction with PAGs, either by using an AFS-modified login utility, +issuing the pagsh command before obtaining tokens, or including the +-setpag flag to the klog command. +

Several configuration requirements and restrictions are necessary for token +passing to work correctly with the AFS version of the rsh +command. Some of these are also necessary with the standard UNIX +version, but are included here because the issuer used to AFS protections is +possibly unlikely to think of them. There are possibly other UNIX-based +requirements or restrictions not mentioned here; consult the UNIX manual +page for the rsh command. (One important one is that no +stty commands can appear in the issuer's shell initialization +file, such as the .cshrc file.) +

The requirements and restrictions for token passing include the +following. +

The local machine must be running the AFS version of the rsh +command, with the binary file locally installed to grant setuid privilege to +the owner, the local superuser root. +
The remote machine must be running the AFS version of the inetd +program. +
If the rsh command is to consult an .rhosts +file on the remote machine, the file must have UNIX mode bits no more liberal +than -rw-r--r--. If the .rhosts file +resides in a user home directory in AFS, the home directory must also grant +the l (lookup) and r (read) +permissions to the system:anyuser group. +

Options +

Consult the UNIX manual page for the rsh command. +

Privilege Required +

None +

Related Information +

UNIX manual page for rsh or remsh +

IBM AFS Release Notes +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf230.htm b/doc/html/AdminReference/auarf230.htm new file mode 100644 index 0000000..4e25d46 --- /dev/null +++ b/doc/html/AdminReference/auarf230.htm @@ -0,0 +1,123 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

runntp

+ + + + + + + +

Purpose +

Initializes the Network Time Protocol Daemon +

Synopsis +

runntp [-localclock] [-precision <small negative integer>]  
+       [-logfile <filename for ntpd's stdout/stderr>]  
+       [-ntpdpath <pathname of ntpd executable (/usr/afs/bin/ntpd)>]  
+       [<host>⁺] [-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 runntp command initializes the Network Time Protocol Daemon +(NTPD) and related programs on the local machine and constructs an +ntp.conf configuration file. The intended use is on +AFS file server machines as a convenient interface to the standard +ntpd program. +

In the conventional configuration, the binary file for the command is +located in the /usr/afs/bin directory on a file server +machine. The command is not normally issued at the command shell +prompt, but rather placed into a file server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a server machine as the local superuser +root. +

Cautions +

Do not run the runntp program if NTPD or another time protocol +is already in use in the cell. Running two time-synchronization +protocols can cause errors. +

Options +

-localclock +

Designates the local machine's internal clock as a possible time +source if a network partition separates the machine from the other source +machines listed on the command line. In cells that are not connected to +an exterior network or are behind a firewall, include this flag on every +machine that runs the runntp process. In cells that +frequently lose access to exterior networks (voluntarily or not), include it +only on the runntp process running on the system control +machine. Do not include the flag if the cell is reliably connected to +exterior networks. +

-precision +

Specifies the precision of the local clock. This argument is not +normally provided. As the ntpd process initializes, it +determines the precision of the local clock on its own. If provided, it +is a small integer preceded by a hyphen to show that it is negative. +The value is used as an exponent on the number 2, and the result interpreted +as the frequency, in fractions of a second, at which the local clock ticks +(advances). +

For example, a value of -6, which translates to +2^-6 or 1/64, means that the local clock ticks once every +1/64th of a second, or has a precision of about 60 ticks per second. A +value of -7 translates to about 100 ticks per second. A +value of -10 translates to about 1000 ticks per second (a +millisecond clock). +

-logfile +

Specifies the local disk pathname for the NTP daemon's log file, such +as /usr/afs/logs/ntp.log. The log records which +machines are serving as time sources and peers, what adjustments have been +made to reduce drift, and so on. Use the ntpd process's +debugging mechanism to control the amount of information produced. If +this argument is omitted, the information is discarded. +

-ntpdpath +

Specifies the local disk pathname of the binary for the ntpd +program. If this argument is omitted, the default is +/usr/afs/bin/ntpd. +

host +

Is the fully qualified hostname of each machine to consult as a time +source. By convention, the machines are outside the cell if exterior +networks are accessible. +

In general, this argument is necessary only on the system control +machine. If the issuer omits it, then the local machine consults the +local database server machines listed in its copy of the +/usr/afs/etc/CellServDB file. +

For advice on selecting appropriate time sources, see the IBM AFS +Quick Beginnings or ask AFS Product Support. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Privilege Required +

Related Information +

UNIX manual page for ntp +

UNIX manual page for ntpd +

UNIX manual page for ntpdc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf231.htm b/doc/html/AdminReference/auarf231.htm new file mode 100644 index 0000000..bdb5774 --- /dev/null +++ b/doc/html/AdminReference/auarf231.htm @@ -0,0 +1,168 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

rxdebug

+ + + +

Purpose +

Provides debugging trace of Rx activity +

Synopsis +

rxdebug -servers <server machine>  [-port <IP port>]  [-nodally]  
+        [-allconnections]  [-rxstats] [-onlyserver]  [-onlyclient]  
+        [-onlyport <show only <port>>]  [-onlyhost <show only <host>>]  
+        [-onlyauth <show only <auth level>>]  [-version]  [-noconns]  
+        [-peers]  [-help] 
+   
+rxdebug -s <server machine>  [-po <IP port>]  [-nod]  [-a]  [-r]  
+        [-onlys]  [-onlyc]   [-onlyp <show only <port>>]  
+        [-onlyh <show only <host>>]  [-onlya <show only <auth level>>]  
+        [-v]  [-noc]  [-pe]  [-h] 
+

Description +

The rxdebug command provides a trace of Rx activity for the +server or client machine named by the -servers argument. Rx +is AFS's proprietary remote procedure call (RPC) protocol, so this +command enables the issuer to check the status of communication between the +Cache Manager or an AFS server process (as specified with the -port +argument) on the machine and one or more processes on other machines. +

Options +

-servers +

Specifies the machine that is running the Cache Manager or server process +for which to trace Rx activity. Provide the machine's IP address +in dotted decimal format, its fully qualified host name (for example, +fs1.abc.com), or the shortest abbreviated form of its +host name that distinguishes it from other machines. Successful use of +an abbreviated form depends on the availability of a name resolution service +(such as the Domain Name Service or a local host table) at the time the +command is issued. +

-port +

Specifies the process for which to trace Rx activity. Omit this +argument to specify the File Server (fileserver process), or +provide one of the following values: +

7000 for the File Server (fileserver process) +

7001 for the Cache Manager (specifically, its callback +interface) +

7002 for the Protection Server (ptserver process) +

7003 for the Volume Location (VL) Server (vlserver +process) +

7004 for the Authentication Server (kaserver +process) +

7005 for the Volume Server (volserver process) +

7007 for the BOS Server (bosserver process) +

7008 for the Update Server (upserver process) +

7009 for the NFS/AFS Translator's rmtsysd +daemon +

7021 for the Backup Server (buserver process) +

7025 through 65535 for the Backup Tape Coordinator +(butc process) that has the port offset number derived by +subtracting 7025 from this value +

-nodally +

Produces output only for connections that are not in dally mode. +

-allconnections +

Produces output for all connections, even inactive ones. By +default, the output includes information only for connections that are active +or in dally mode when the rxdebug command is issued. +

-rxstats +

Produces detailed statistics about Rx history and performance (for +example, counts of the number of packets of various types the process has read +and sent, calculations of average and minimum roundtrip time, and so +on). +

-onlyserver +

Produces output only for connections in which the process designated by +the -port argument is acting as the server. +

-onlyclient +

Produces output only for connections in which the process designated by +the -port argument is acting as the client. +

-onlyport +

Produces output only for connections between the process designated by the +-port argument and the specified port on any another +machine. Use the same port identifiers as for the -port +argument. +

-onlyhost +

Produces output only for connections between the process designated by the +-port argument and any process on the specified machine. To +identify the machine, use the same notation as for the -servers +argument. +

-onlyauth +

Produces output only for connections that are using the specified +authentication level. Provide one of the following values: +

auth for connections at authentication level +rxkad_auth +
clear for connections at authentication level +rxkad_clear +
crypt for connections at authentication level +rxkad_crypt +
none for unauthenticated connections (equivalents are +null, noauth, and unauth) +

-version +

Reports the AFS build level of the binary file for the process designated +by the -port argument (or of the kernel extensions file for port +7001, the Cache Manager's callback interface). Any other options +combined with this one are ignored. +

-noconns +

Produces only the standard statistics that begin the output produced by +every option (other than -version), without reporting on any +connections. Any other options combined with this one are +ignored. +

-peers +

Outputs information from the peer structure maintained for each +port on another machine to which the process designated by the +-port argument has a connection. There is information about +roundtrip time and numbers of packets sent and received, for example. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

If any options other than -version or -help are +provided, the output written to the standard output stream begins with basic +statistics about packet usage and availability, how many calls are waiting for +a thread, how many threads are free, and so on (this is the only information +provided by the -noconns flag). Adding other options +produces additional information as described in the preceding +Options section of this reference page. The output is +intended for debugging purposes and is meaningful to someone familiar with the +implementation of Rx. +

Privilege Required +

None. +

Related Information +

afsd +

butc +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf232.htm b/doc/html/AdminReference/auarf232.htm new file mode 100644 index 0000000..b00311e --- /dev/null +++ b/doc/html/AdminReference/auarf232.htm @@ -0,0 +1,265 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

salvager

+ + + + +

Purpose +

Initializes the Salvager component of the fs process +

Synopsis +

salvager [initcmd]  [-partition <Name of partition to salvage>] 
+         [-volumeid <Volume Id to salvage>]  [-debug]  
+         [-nowrite]  [-inodes]  [-force]  [-oktozap]  
+         [-rootinodes]  [-salvagedirs]  [-blockreads]  
+         [-parallel <# of max parallel partition salvaging>]
+         [-tmpdir <Name of dir to place tmp files>]  
+         [-showlog]  [-showsuid]  [-showmounts] 
+         [-orphans <ignore | remove | attach>] [-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 salvager command initializes the Salvager component of the +fs process. In the conventional configuration, its binary +file is located in the /usr/afs/bin directory on a file server +machine. +

The Salvager restores internal consistency to corrupted read/write volumes +on the local file server machine where possible. For read-only or +backup volumes, it inspects only the volume header: +

If the volume header is corrupted, the Salvager removes the volume +completely and records the removal in its log file, +/usr/afs/logs/SalvageLog. Issue the vos release +or vos backup command to create the read-only or backup volume +again. +
If the volume header is intact, the Salvager skips the volume (does not +check for corruption in the contents). However, if the File Server +notices corruption as it initializes, it sometimes refuses to attach the +volume or bring it online. In this case, it is simplest to remove the +volume by issuing the vos remove or vos zap +command. Then issue the vos release or vos backup +command to create it again. +

Unlike other server process initialization commands, the +salvager command is designed to be issued at the command shell +prompt, as well as being placed into a file server machine's +/usr/afs/local/BosConfig file with the bos create +command. It is also possible to invoke the Salvager remotely by issuing +the bos salvage command. +

Combine the command's options as indicated to salvage different +numbers of read/write volumes: +

To salvage all volumes on the file server machine, provide no +arguments. No volumes on the machine are accessible to Cache Managers +during the salvage, because the BOS Server stops the File Server and Volume +Server processes while the Salvager runs. +
To salvage all of the volumes on one partition, provide the +-partition argument. As for a salvage of all volumes on the +machine, no volumes on the machine are accessible to Cache Managers during the +salvage operation. +
To salvage only one volume, combine the -partition and +-volumeid arguments. Only that volume is inaccessible to +Cache Managers, because the BOS Server does not shutdown the File Server and +Volume Server processes. +

The Salvager normally salvages only those read/write volumes that are +marked as having been active when a crash occurred. To have it salvage +all relevant read/write volumes, add the -force flag. +

The Salvager normally creates new inodes as it repairs damage. If +the partition is so full that there is no room for new inodes, use the +-nowrite argument to bringing undamaged volumes online without +attempting to salvage damaged volumes. Then use the vos move +command to move one or more of the undamaged volumes to other partitions, +freeing up the space that the Salvager needs to create new inodes. +

To generate a list of all mount points that reside in one or more volumes, +rather than actually salvaging them, include the -showmounts +flag. +

Options +

initcmd +

Accommodates the command's use of the AFS command parser, and is +optional. +

-partition +

Specifies the name of the partition to salvage. Specify the full +partition name using the form /vicepx or +/vicepxx. Omit this argument to salvage every +partition on the file server machine. +

-volumeid +

Specifies the volume ID of a specific read/write volume to salvage. +The -partition argument must be provided along with this one and +specify the volume's actual site. +

-debug +

Allows only one Salvager subprocess to run at a time, regardless of the +setting of the -parallel option. Include it when running the +Salvager in a debugger to make the trace easier to interpret. +

-nowrite +

Brings all undamaged volumes online without attempting to salvage any +damaged volumes. +

-inodes +

Records in the /usr/afs/logs/SalvageLog file a list of all AFS +inodes that the Salvager modified. +

-force +

Inspects all volumes for corruption, not just those that are marked as +having been active when a crash occurred. +

-oktozap +

Removes a volume that is so damaged that even issuing the vos +zap command with the -force flag is ineffective. Use +this argument only in consultation with AFS Development or Product +Support. Combine it with the -partition and +-volumeid arguments to identify the volume to remove. +

-rootinodes +

Records in the /usr/afs/logs/SalvageLog file a list of all AFS +inodes owned by the local superuser root. +

-salvagedirs +

Salvages entire directory structures, even if they do not appear to be +damaged. By default, the Salvager salvages a directory only if it is +flagged as corrupted. +

-blockreads +

Forces the Salvager to read a partition one disk block (512 bytes) at a +time and to skip any blocks that are too badly damaged to be salvaged. +This allows it to salvage as many volumes as possible. By default, the +Salvager reads large disk blocks, which can cause it to exit prematurely if it +encounters disk errors. Use this flag if the partition to be salvaged +has disk errors. +

-parallel +

Specifies the maximum number of Salvager subprocesses to run in +parallel. Provide one of three values: +

An integer from the range 1 to 32. A value of +1 means that a single Salvager process salvages the partitions +sequentially. +
The string all to run up to four Salvager subprocesses in +parallel on partitions formatted as logical volumes that span multiple +physical disks. Use this value only with such logical volumes. +
The string all followed immediately (with no intervening space) +by an integer from the range 1 to 32, to run the +specified number of Salvager subprocesses in parallel on partitions formatted +as logical volumes. Use this value only with such logical +volumes. +

-tmpdir +

Names a local disk directory in which the Salvager places the temporary +files it creates during a salvage operation, instead of writing them to the +partition being salvaged (the default). If the Salvager cannot write to +the specified directory, it attempts to write to the partition being +salvaged. +

-showlog +

Displays on the standard output stream all log data that is being written +to the /usr/afs/logs/SalvageLog file. +

-showsuid +

Displays a list of the pathnames for all files that have the setuid or +setgid mode bit set. +

-showmounts +

Records in the /usr/afs/logs/SalvageLog file all mount points +found in each volume. The Salvager does not repair corruption in the +volumes, if any exists. +

-orphans +

Controls how the Salvager handles orphaned files and directories. +Choose one of the following three values: +

ignore +

remove +

Removes the orphaned objects, and prints a message to the +/usr/afs/logs/SalvageLog file reporting how many orphans were +removed and the approximate number of kilobytes they were consuming. +

attach +

_ _ORPHANFILE_ _.index for files +

_ _ORPHANDIR_ _.index for directories +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command instructs the Salvager to attempt to salvage the +volume with volume ID 258347486 on /vicepg on the local +machine. +

   % /usr/afs/bin/salvager -partition /vicepg -volumeid 258347486
+   
+

Privilege Required +

To issue the command at the shell prompt, the issuer must be logged in as +the local superuser root. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf233.htm b/doc/html/AdminReference/auarf233.htm new file mode 100644 index 0000000..5b046d0 --- /dev/null +++ b/doc/html/AdminReference/auarf233.htm @@ -0,0 +1,283 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

scout

+ + + + + + + + + + +

Purpose +

Monitors the File Server process +

Synopsis +

scout [initcmd]  -server <FileServer name(s) to monitor>⁺
+      [-basename <base server name>]  
+      [-frequency <poll frequency, in seconds>]  [-host]  
+      [-attention <specify attention (highlighting) level>⁺]
+      [-debug <turn debugging output on to the named file>]  [-help]
+    
+scout [i]  -s <FileServer name(s) to monitor>⁺  
+      [-b <base server name>] [-f <poll frequency, in seconds>] 
+      [-ho]  [-a <specify attention (highlighting) level>⁺]
+      [-d <turn debugging output on to the named file>]  [-he]
+

Description +

The scout command displays statistics gathered from the File +Server process running on each machine specified with the -server +argument. The Output section explains the meaning of the +statistics and describes how they appear in the command shell, which is +preferably a window managed by a window manager program. +

Cautions +

The scout program must be able to access the curses +graphics package, which it uses to display statistics. Most UNIX +distributions include curses as a standard utility. +

Both dumb terminals and windowing systems that emulate terminals can +display the scout program's statistics. The display +makes use of reverse video and cursor addressing, so the display environment +must support those features for it to look its best (most windowing systems +do, most dumb terminals do not). Also, set the TERM environment +variable to the correct terminal type, or one with characteristics similar to +the actual ones. For machines running the AIX operating system, the +recommended setting for TERM is vt100, as long as the terminal is +similar to that. For other operating systems, the wider range of +acceptable values includes xterm, xterms, +vt100, vt200, and wyse85. +

Options +

initcmd +

Accommodates the command's use of the AFS command parser, and is +optional. +

-server +

Specifies each file server machine running a File Server process to +monitor. Provide each machine's fully qualified hostname unless +the -basename argument is used. In that case, specify only +the unique initial part of each machine name, omitting the domain name suffix +(the basename) common to all the names. It is also acceptable to use +the shortest abbreviated form of a host name that distinguishes it from other +machines, but successful resolution depends on the availability of a name +resolution service (such as the Domain Name Service or a local host table) at +the time the command is issued. +

-basename +

Specifies the basename (domain name) suffix common to all of the file +server machine names specified with the -server argument, and is +automatically appended to them. This argument is normally the name of +the cell to which the machines belong. Do not include the period that +separates this suffix from the distinguishing part of each file server machine +name, but do include any periods that occur within the suffix itself. +For example, in the ABC Corporation cell, the proper value is +abc.com rather than +.abc.com. +

-frequency +

Indicates how often to probe the File Server processes. Specify a +number of seconds greater than 0 (zero). The default is 60 +seconds. +

-host +

Displays the name of the machine that is running the scout +program, in the banner line of the display screen. +

-attention +

Defines a list of entries, each of which pairs a statistic and a threshold +value. When the value of the statistic exceeds the indicated threshold +value, it is highlighted (in reverse video) in the display. List the +pairs in any order. The acceptable values are the following: +

conn connections. Indicates the number of open +connections to client processes at which to highlight the statistic. +The statistic returns to regular display when the value goes back below the +threshold. There is no default threshold. +
An example of an acceptable value is conn 300. +
disk, which takes one of two types of values: +
- disk blocks_free. Indicates the number of +remaining free kilobyte blocks at which to highlight the statistic. The +statistic returns to regular display when the value again exceeds the +threshold. There is no default threshold. +
  An example of an acceptable value is disk 5000. +
- disk percent_full%. Indicates the +percentage of disk usage at which to highlight the statistic. The +statistic returns to regular display when the value goes back below the +threshold. The default threshold is 95%. Acceptable values are +the integers in the range from 0 to 99, followed by the +percent sign (%) to distinguish this type of value from the one +described just previously. +
  An example is disk 90%. +
+
fetch fetch_RPCs. Indicates the cumulative +number of fetch RPCs from client processes at which to highlight the +statistic. The statistic does not return to regular display until the +File Server process restarts, at which time the value returns to zero. +There is no default threshold. +
Example of a legal value: fetch 6000000 +
store store_RPCs. Indicates the cumulative +number of store RPCs from client processes at which to highlight the +statistic. The statistic does not return to regular display until the +File Server process restarts, at which time the value returns to zero. +There is no default threshold. +
Example of an acceptable value: store 200000 +
ws active_client_machines. Indicates the number +of client machines with active open connections at which to highlight the +statistic. An active connection is defined as one over which the File +Server and client have communicated in the last 15 minutes. The +statistic returns to regular display when the value goes back below the +threshold. There is no default threshold. +
Example of an acceptable value: ws 65 +

-debug +

Specifies the pathname of the file into which to write a debugging +trace. Partial pathnames are interpreted relative to the current +working directory. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The scout program can display statistics either in a dedicated +window or on a plain screen if a windowing environment is not +available. For best results, the window or screen needs the ability to +print in reverse video. +

The scout screen has three main parts: the banner line, +the statistics display region and the message/probe line. +

The Banner Line +

By default, the string Scout appears in the banner line at the +top of the window or screen. Two optional arguments place additional +information in the banner line: +

The -host flag displays the name of the machine where the +scout program is running. As mentioned previously, this is +useful when running the scout program on several machines but +displaying the results on a single machine. +
For example, when the -host flag is included and the +scout program is running on the machine +client1.abc.com, the banner line reads as +follows: +
```
   [client1.abc.com] Scout
+   
+
```
+
The -basename argument displays the indicated basename on the +banner line. For example, including the argument -basename +abc.com argument results in the following banner line: +
```
   Scout for abc.com
+   
+
```
+

The Statistics Display Region +

In this region, which occupies the majority of the window, the +scout process displays the statistics gathered for each File Server +process. Each process appears on its own line. +

The region is divided into six columns, labeled as indicated and displaying +the following information: + + +

Conn: The first column displays the number of RPC +connections open between the File Server process and client machines. +This number equals or exceeds the number in the Ws column (see the +fourth entry below), because each user on the machine can have several +separate connections open at once, and one client machine can handle several +users. + +
Fetch: The second column displays the number of +fetch-type RPCs (fetch data, fetch access list, and fetch status) that client +machines have made to the File Server process since the latter started. +This number is reset to zero each time the File Server process +restarts. + +
Store: The third column displays the number of store-type +RPCs (store data, store access list, and store status) that client machines +have made to the File Server process since the latter started. This +number is reset to zero each time the File Server process restarts. + +
Ws: The fourth column displays the number of client +machines (Ws stands for workstations) that have communicated with +the File Server process within the last 15 minutes. Such machines are +termed active). This number is likely to be smaller than the +number in the first (Conn) column because a single client machine +can have several connections open to one File Server. + + + +
The fifth, unlabeled, column displays the name of the file server machine +on which the File Server process is running. Names of 12 characters or +less are displayed in full; longer names are truncated and an asterisk +(*) appears as the last character in the name. Using the +-basename argument is a good way to avoid truncation, but only if +all machine names end in a common string. +
Disk attn: The sixth column displays the number of +available kilobyte blocks on each AFS disk partition on the file server +machine. + + + + The display for each partition has the following form: +
```
   x:free_blocks
+   
+
```
+
where x indicates the partition name. For example, +a:8949 specifies that the /vicepa +partition has 8,949 1-KB blocks free. Available space can be displayed +for up to 26 partitions. If the window is not wide enough for all +partition entries to appear on a single line, the scout process +automatically creates multiple lines, stacking the partition entries into +sub-columns within the sixth column. +
The label on the Disk attn column indicates the +threshold value at which entries in the column become highlighted. By +default, the label is +
```
   Disk attn: > 95% used
+   
+
```
+
because by default the scout program highlights the entry for +any partition that is over 95% full. +

For all columns except the fifth (file server machine name), the optional +-attention argument sets the value at which entries in the column +are highlighted to indicate that a certain value has been exceeded. +Only values in the fifth and Disk attn columns ever become +highlighted by default. +

If the scout program is unable to access or otherwise obtain +information about a partition, it generates a message similar to the following +example: +

   Could not get information on server fs1.abc.com partition /vicepa
+   
+

The Message/Probe Line +

The bottom line of the scout screen indicates how many times the +scout program has probed the File Server processes for +statistics. The statistics gathered in the latest probe appear in the +statistics display region. The -frequency argument overrides +the default probe frequency of 60 seconds. +

Examples +

See the chapter on monitoring tools in the IBM AFS Administration +Guide, which illustrates the displays that result from different +combinations of options. +

Privilege Required +

None +

Related Information +

afsmonitor +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf234.htm b/doc/html/AdminReference/auarf234.htm new file mode 100644 index 0000000..d960059 --- /dev/null +++ b/doc/html/AdminReference/auarf234.htm @@ -0,0 +1,67 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

sys

Purpose + + + + + + + +

Reports the CPU/operating system type +

Synopsis +

sys 
+

Description +

The sys command displays the string stored in kernel memory that +indicates the local machine's CPU/operating system (OS) type. The +Cache Manager substitutes the string for the @sys variable which can +occur in AFS pathnames; the IBM AFS Quick Beginnings and +IBM AFS Administration Guide explain how using @sys can +simplify cell configuration. +

The command always reports the value for the local machine only. To +set a new value in kernel memory, use the fs sysname command, which +like this command can also be used to display the current value. +

Output +

The machine's system type appears as a text string: +

   system_type
+   
+

Examples +

The following example shows the output produced on a Sun SPARCStation +running Solaris 5.7: +

   % sys
+   sun4x_57
+   
+

Privilege Required +

None +

Related Information +

fs sysname +

IBM AFS Quick Beginnings +

IBM AFS Administration Guide +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf235.htm b/doc/html/AdminReference/auarf235.htm new file mode 100644 index 0000000..b746a78 --- /dev/null +++ b/doc/html/AdminReference/auarf235.htm @@ -0,0 +1,124 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

tokens

+ + + + + + +

Purpose +

Displays the issuer's tokens +

Synopsis +

tokens [-help]
+   
+tokens [-h]
+

Description +

The tokens command displays all tokens (tickets) cached on the +local machine for the issuer. AFS server processes require that their +clients present a token as evidence that they have authenticated in the +server's local cell. +
Note: The tokens.krb version of this command is intended for use +by sites that employ standard Kerberos authentication for their +clients. The tokens.krb command provides all of the +functionality of the tokens command. In addition, it +provides information on the Kerberos tickets stored in the file specified by +the KRBTKFILE environment variable (the /tmp/tktX file, +where X is the number of the user's PAG). +
+

Options +

-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output lists one token for each cell in which the user is +authenticated. The output indicates the +

User's AFS UID, if it is available for display. +
Server for which the token is valid (normally, afs). +This includes a cell specification. +
Day and time the token expires. +

The output of the Kerberos version of this command, +tokens.krb, also reports the following about the Kerberos +ticket-granting ticket: the ticket owner, which Kerberos ticket-granting +service that issued the ticket (for example, +krbtgt.ABC.COM), and ticket's expiration +date. +

The string --End of list-- appears at the end of the +output. If the user is not authenticated in any cell, this line is all +that appears. +

Examples +

The following example shows the output when the issuer is not authenticated +in any cell. +

   % tokens
+   Tokens held by the Cache Manager:
+   
+      --End of list--
+   
+

The following example shows the output when the issuer is authenticated in +ABC Corporation cell, where he or she has AFS UID 1000. +

   % tokens
+   Tokens held by the Cache Manager:
+   
+   User's (AFS ID 1000) tokens for afs@abc.com [Expires Jan 2 10:00]
+      --End of list--
+   
+

The following example shows the output when the issuer is authenticated in +the ABC Corporation cell, the State University cell, and the XYZ Company +cell. The user has different AFS UIDs in the three cells. Tokens +for last cell are expired: +

   % tokens
+   Tokens held by the Cache Manager:
+      
+   User's (AFS ID 1000) tokens for afs@abc.com [Expires Jan 3 10:00]
+   User's (AFS ID 4286) tokens for afs@stateu.edu [Expires Jan 3 1:34]
+   User's (AFS ID 22) tokens for afs@xyz.com [>>Expired<]
+      --End of list--
+   
+

The following example shows the output when the issuer uses the +tokens.krb version of the command after authenticating in +the ABC Corporation cell using the klog.krb command. +

   % tokens.krb
+   Tokens held by the Cache Manager:
+      
+   User's (AFS ID 1000) tokens for afs@abc.com [Expires Jan 31 00:09]
+   User smiths tokens for krbtgt.ABC.COM@abc.com [Expires Jan 31 00:09]
+      --End of list--
+   
+

Privilege Required +

None +

Related Information +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf236.htm b/doc/html/AdminReference/auarf236.htm new file mode 100644 index 0000000..4a60eda --- /dev/null +++ b/doc/html/AdminReference/auarf236.htm @@ -0,0 +1,54 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

translate_et

+ + + +

Purpose +

Translates numbered error codes into text messages +

Synopsis +

translate_et  <error number>⁺
+

This command does not use the syntax conventions of the AFS command +suites. Provide the command name in full. +

Description +

The translate_et command translates each specified error number +into a text message. +

Options +

error number +: Specifies each error number to translate. +

Examples +

The following command translates the error numbers 1 and 4: +

   % translate_et 1 4
+   1 ().1 = Not owner
+   4 ().4 = Interrupted system call
+   
+

Privilege Required +

None +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf237.htm b/doc/html/AdminReference/auarf237.htm new file mode 100644 index 0000000..64470ac --- /dev/null +++ b/doc/html/AdminReference/auarf237.htm @@ -0,0 +1,325 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

udebug

+ + + +

Purpose +

Reports status of Ubik process associated with a database server process +

Synopsis +

udebug -servers  <server machine>  [-port <IP port>]  [-long]  [-help]
+        
+udebug -s  <server machine>  [-p <IP port>]  [-l]  [-h]
+        
+

Description +

The udebug command displays the status of the lightweight Ubik +process for the database server process identified by the -port +argument that is running on the database server machine named by the +-servers argument. The output identifies the machines where +peer database server processes are running, which of them is the +synchronization site (Ubik coordinator), and the status of the connections +between them. +

Options +

-servers +

Names the database server machine that is running the process for which to +display status information. Provide the machine's IP address in +dotted decimal format, its fully qualified host name (for example, +fs1.abc.com), or the shortest abbreviated form of its +host name that distinguishes it from other machines. Successful use of +an abbreviated form depends on the availability of a name resolution service +(such as the Domain Name Service or a local host table) at the time the +command is issued. +

-port +

Identifies the database server process for which to display status +information, either by its process name or port number. Provide one of +the following values. +

buserver or 7021 for the Backup Server +

kaserver or 7004 for the Authentication Server +

ptserver or 7002 for the Protection Server +

vlserver or 7003 for the Volume Location Server +

-long +

Reports additional information about each peer of the machine named by the +-servers argument. The information appears by default if +that machine is the synchronization site. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

Several of the messages in the output provide basic status information +about the Ubik process on the machine specified by the -servers +argument, and the remaining messages are useful mostly for debugging +purposes. +

To check basic Ubik status, issue the command for each database server +machine in turn. In the output for each, one of the following messages +appears in the top third of the output. +

   I am sync site . . . (#_sites servers)
+   
+   I am not sync site 
+

For the synchronization site, the following message indicates that all +sites have the same version of the database, which implies that Ubik is +functioning correctly. See the following for a description of values +other than 1f. +

   Recovery state 1f
+

For correct Ubik operation, the database server machine clocks must agree +on the time. The following messages, which are the second and third +lines in the output, report the current date and time according to the +database server machine's clock and the clock on the machine where the +udebug command is issued. +

   Host's IP_addr time is dbserver_date/time
+   Local time is local_date/time (time differential skew secs)
+

The skew is the difference between the database server machine +clock and the local clock. Its absolute value is not vital for Ubik +functioning, but a difference of more than a few seconds between the +skew values for the database server machines indicates that their +clocks are not synchronized and Ubik performance is possibly hampered. +

Following is a description of all messages in the output. As noted, +it is useful mostly for debugging and most meaningful to someone who +understands Ubik's implementation. +

The output begins with the following messages. The first message +reports the IP addresses that are configured with the operating system on the +machine specified by the -servers argument. As previously +noted, the second and third messages report the current date and time +according to the clocks on the database server machine and the machine where +the udebug command is issued, respectively. All subsequent +timestamps in the output are expressed in terms of the local clock rather than +the database server machine clock. +

   Host's addresses are: list_of_IP_addrs
+   Host's IP_addr time is dbserver_date/time
+   Local time is local_date/time (time differential skew secs)
+

If the skew is more than about 10 seconds, the following message +appears. As noted, it does not necessarily indicate Ubik +malfunction: it denotes clock skew between the database server machine +and the local machine, rather than among the database server machines. +

   ****clock may be bad
+

If the udebug command is issued during the coordinator election +process and voting has not yet begun, the following message appears +next. +

   Last yes vote not cast yet
+

Otherwise, the output continues with the following messages. +

   Last yes vote for sync_IP_addr was last_vote secs ago (sync site); 
+   Last vote started vote_start secs ago (at date/time)
+   Local db version is db_version
+

The first indicates which peer this Ubik process last voted for as +coordinator (it can vote for itself) and how long ago it sent the vote. +The second message indicates how long ago the Ubik coordinator requested +confirming votes from the secondary sites. Usually, the +last_vote and vote_start values are the same; a +difference between them can indicate clock skew or a slow network connection +between the two database server machines. A small difference is not +harmful. The third message reports the current version number +db_version of the database maintained by this Ubik process. It +has two fields separated by a period. The field before the period is +based on a timestamp that reflects when the database first changed after the +most recent coordinator election, and the field after the period indicates the +number of changes since the election. +

The output continues with messages that differ depending on whether the +Ubik process is the coordinator or not. +

If there is only one database server machine, it is always the coordinator +(synchronization site), as indicated by the following message. +
```
   I am sync site forever (1 server)
+
```
+
If there are multiple database sites, and the -servers argument +names the coordinator (synchronization site), the output continues with the +following two messages. +
```
   I am sync site until expiration secs from now (at date/time) (#_sites servers)
+   Recovery state flags
+
```
+
The first message reports how much longer the site remains coordinator even +if the next attempt to maintain quorum fails, and how many sites are +participating in the quorum. The flags field in the second +message is a hexadecimal number that indicates the current state of the +quorum. A value of 1f indicates complete database +synchronization, whereas a value of f means that the coordinator +has the correct database but cannot contact all secondary sites to determine +if they also have it. Lesser values are acceptable if the +udebug command is issued during coordinator election, but they +denote a problem if they persist. The individual flags have the +following meanings: +
+
0x1 +
This machine is the coordinator +
0x2 +
The coordinator has determined which site has the database with the +highest version number +
0x4 +
The coordinator has a copy of the database with the highest version number +
0x8 +
The database's version number has been updated correctly +
0x10 +
All sites have the database with the highest version number +
+
If the udebug command is issued while the coordinator is writing +a change into the database, the following additional message appears. +
```
   I am currently managing write transaction identifier
+
```
+
If the -servers argument names a secondary site, the output +continues with the following messages. +
```
   I am not sync site
+   Lowest host lowest_IP_addr was set low_time secs ago
+   Sync host sync_IP_addr  was set sync_time secs ago
+
```
+
The lowest_IP_addr is the lowest IP address of any peer from which +the Ubik process has received a message recently, whereas the +sync_IP_addr is the IP address of the current coordinator. If +they differ, the machine with the lowest IP address is not currently the +coordinator. The Ubik process continues voting for the current +coordinator as long as they remain in contact, which provides for maximum +stability. However, in the event of another coordinator election, this +Ubik process votes for the lowest_IP_addr site instead (assuming they +are in contact), because it has a bias to vote in elections for the site with +the lowest IP address. +

For both the synchronization and secondary sites, the output continues with +the following messages. The first message reports the version number of +the database at the synchronization site, which needs to match the +db_version reported by the preceding Local db version +message. The second message indicates how many VLDB records are +currently locked for any operation or for writing in particular. The +values are nonzero if the udebug command is issued while an +operation is in progress. +

     Sync site's db version is db_version
+   locked locked pages, writes of them for write
+

The following messages appear next only if there are any read or write +locks on database records: +

   There are read locks held
+   There are write locks held
+

Similarly, one or more of the following messages appear next only if there +are any read or write transactions in progress when the udebug +command is issued: +

   There is an active write transaction
+   There is at least one active read transaction
+   Transaction tid is tid
+

If the machine named by the -servers argument is the +coordinator, the next message reports when the current coordinator last +updated the database. +

    Last time a new db version was labelled was:
+            last_restart secs ago (at date/time)
+

If the machine named by the -servers argument is the +coordinator, the output concludes with an entry for each secondary site that +is participating in the quorum, in the following format. +

   Server( IP_address ): (db db_version)
+   last vote rcvd last_vote secs ago (at date/time),
+   last beacon sent last_beacon secs ago (at date/time), last vote was { yes | no }
+   dbcurrent={ 0 | 1 }, up={ 0 | 1 } beaconSince={ 0 | 1 }
+

The first line reports the site's IP address and the version number of +the database it is maintaining. The last_vote field reports +how long ago the coordinator received a vote message from the Ubik process at +the site, and the last_beacon field how long ago the coordinator last +requested a vote message. If the udebug command is issued +during the coordinator election process and voting has not yet begun, the +following messages appear instead. +

   Last vote never rcvd
+   Last beacon never sent
+

On the final line of each entry, the fields have the following +meaning: +

dbcurrent is 1 if the site has the database with the +highest version number, 0 if it does not +
up is 1 if the Ubik process at the site is +functioning correctly, 0 if it is not +
beaconSince is 1 if the site has responded to the +coordinator's last request for votes, 0 if it has not +

Including the -long flag produces peer entries even when the +-servers argument names a secondary site, but in that case only the +IP_address field is guaranteed to be accurate. For example, +the value in the db_version field is usually 0.0, +because secondary sites do not poll their peers for this information. +The values in the last_vote and last_beacon fields indicate +when this site last received or requested a vote as coordinator; they +generally indicate the time of the last coordinator election. +

Examples +

This example checks the status of the Ubik process for the Volume Location +Server on the machine afs1, which is the synchronization +site. +

   % udebug afs1 vlserver
+   Host's addresses are: 192.12.107.33 
+   Host's 192.12.107.33 time is Wed Oct 27 09:49:50 1999
+   Local time is Wed Oct 27 09:49:52 1999 (time differential 2 secs)
+   Last yes vote for 192.12.107.33 was 1 secs ago (sync site); 
+   Last vote started 1 secs ago (at Wed Oct 27 09:49:51 1999)
+   Local db version is 940902602.674
+   I am sync site until 58 secs from now (at Wed Oct 27 09:50:50 1999) (3 servers)
+   Recovery state 1f
+   Sync site's db version is 940902602.674
+   0 locked pages, 0 of them for write
+   Last time a new db version was labelled was:
+            129588 secs ago (at Mon Oct 25 21:50:04 1999)
+   
+   Server( 192.12.107.35 ): (db 940902602.674)
+       last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
+       last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
+       dbcurrent=1, up=1 beaconSince=1
+   
+   Server( 192.12.107.34 ): (db 940902602.674)
+       last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
+       last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
+       dbcurrent=1, up=1 beaconSince=1
+

This example checks the status of the Authentication Server on the machine +with IP address 192.12.107.34, which is a secondary +site. The local clock is about 4 minutes behind the database server +machine's clock. +

   % udebug 192.12.107.34 7004
+   Host's addresses are: 192.12.107.34
+   Host's 192.12.107.34 time is Wed Oct 27 09:54:15 1999
+   Local time is Wed Oct 27 09:50:08 1999 (time differential -247 secs)
+   ****clock may be bad
+   Last yes vote for 192.12.107.33 was 6 secs ago (sync site); 
+   Last vote started 6 secs ago (at Wed Oct 27 09:50:02 1999)
+   Local db version is 940906574.25
+   I am not sync site
+   Lowest host 192.12.107.33 was set 6 secs ago
+   Sync host 192.12.107.33 was set 6 secs ago
+   Sync site's db version is 940906574.25
+   0 locked pages, 0 of them for write
+

Privilege Required +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf238.htm b/doc/html/AdminReference/auarf238.htm new file mode 100644 index 0000000..9b8d30a --- /dev/null +++ b/doc/html/AdminReference/auarf238.htm @@ -0,0 +1,80 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

unlog

+ + + + + + +

Purpose +

Discards all of the issuer's tokens +

Synopsis +

unlog [-cell <cell name>⁺]  [-help]
+   
+unlog [-c <cell name>⁺]  [-h]
+

Description +

The unlog command by default discards all tokens that the issuer +currently holds. To discard tokens for certain cells only, name them +with the -cell argument. +

Since a token pertains to one client machine only, destroying tokens on one +machine has no effect on tokens on another machine. +

Cautions +

Specifying one or more cell names can cause a brief authentication outage +during which the issuer has no valid tokens in any cell. This is +because the command actually discards all tokens and then restores the ones +for cells not named by the -cell argument. The outage can +sometimes interrupt the operation of jobs that require authentication. +

Options +

-cell +: Specifies each cell for to discard the token. If this argument is +omitted, the Cache Manager discards all tokens. Provide the fully +qualified domain name, or a shortened form, in which case successful +resolution depends on the availability of a name resolution service (such as +the Domain Name Service or a local host table) at the time the command is +issued. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command discards all tokens. +

   % unlog
+   
+

The following command discards only the tokens for the +abc.com and stateu.edu cells. +

   % unlog -cell abc.com stateu
+   
+

Privilege Required +

None +

Related Information +

klog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf239.htm b/doc/html/AdminReference/auarf239.htm new file mode 100644 index 0000000..1f8e9fb --- /dev/null +++ b/doc/html/AdminReference/auarf239.htm @@ -0,0 +1,113 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

up

+ + + +

Purpose +

Recursively copies the contents of a source directory to a destination +directory. +

Synopsis +

up [-v]  [-1]  [-f]  [-r]  [-x]  <source directory>  <destination directory>
+

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 up command recursively copies the files and subdirectories +in a specified source directory to a specified destination directory. +The command interpreter changes the destination directory and the files and +subdirectories in it in the following ways: +

It copies the source directory's access control list (ACL) to the +destination directory and its subdirectories, overwriting any existing +ACLs. +
If the issuer is logged on as the local superuser root and has +AFS tokens as a member of the group system:administrators, +then the source directory's owner (as reported by the ls -ld +command) becomes the owner of the destination directory and all files and +subdirectories in it. Otherwise, the issuer's user name is +recorded as the owner. +
If a file or directory exists in both the source and destination +directories, the source version overwrites the destination version. The +overwrite operation fails if the first (user) w (write) +mode bit is turned off on the version in the destination directory, unless the +-f flag is provided. +
The modification timestamp on a file (as displayed by the ls -l +command) in the source directory overwrites the timestamp on a file of the +same name in the destination directory, but the timestamp on an existing +subdirectory in the destination directory remains unchanged. If the +command creates a new subdirectory in the destination directory, the new +subdirectory's timestamp is set to the time of the copy operation, rather +than to the timestamp that the subdirectory has in the source +directory. +

The up command is idempotent, meaning that if its execution is +interrupted by a network, server machine, or process outage, then a subsequent +reissue of the same command continues from the interruption point, rather than +starting over at the beginning. This saves time and reduces network +traffic in comparison to the UNIX commands that provide similar +functionality. +

The up command returns a status code of 0 (zero) only +if it succeeds. Otherwise, it returns a status code of 1 +(one). +

Options +

-v +: Prints a detailed trace to the standard output stream as the command +runs. +
-1 +: Copies only the files in the top level source directory to the destination +directory, rather than copying recursively through subdirectories. The +source directory's ACL still overwrites the destination +directory's. (This is the number one, not the letter +l.) +
-f +: Overwrites existing directories, subdirectories, and files even if the +first (user) w (write) mode bit is turned off on the +version in the destination directory. +
-r +: Creates a backup copy of all files overwritten in the destination +directory and its subdirectories, by adding a .old extension +to each filename. +
-x +: Sets the modification timestamp on each file to the time of the copying +operation. +
source directory +: Names the directory to copy recursively. +
destination directory +: Names the directory to which to copy. It does not have to exist +already. +

Examples +

The following command copies the contents of the directory dir1 to +directory dir2: +

   % up dir1 dir2
+   
+

Privilege Required +

The issuer must have the a (administer) permission on +the ACL of both the source and destination directories. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf240.htm b/doc/html/AdminReference/auarf240.htm new file mode 100644 index 0000000..5236978 --- /dev/null +++ b/doc/html/AdminReference/auarf240.htm @@ -0,0 +1,161 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

upclient

+ + + + + + +

Purpose +

Initializes the client portion of the Update Server +

Synopsis +

upclient <hostname>  [-crypt]  [-clear]  [-t <retry time>]
+         [-verbose]^*  <dir>⁺  [-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 upclient command initializes the client portion of the +Update Server. In the conventional configuration, its binary file is +located in the /usr/afs/bin directory on a file server +machine. +

The upclient command is not normally issued at the command shell +prompt but rather placed into a file server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a database server machine as the local superuser +root. +

The upclient process periodically checks that all files in each +local directory named by the dir argument match the files in the +corresponding directory on the source machine named by the +hostnameargument. If a file does not match, the +upclient process requests the source copy from the +upserver process running on the source machine. +

By default, the upclient process in the United States edition of +AFS requests that the upserver process encrypt the data before +transferring it, whereas in the international edition it requests unencrypted +transfer. If using the United States edition, use the -clear +flag to request unencrypted transfer if appropriate. (The +-crypt flag explicitly sets the default in the United States +edition, and is not available in the international edition.) +

In the conventional configuration, separate instances of the +upclient process request data from the /usr/afs/bin and +/usr/afs/etc directories, except on machines for which the system +control machine is also the binary distribution machine for the machine's +system type. The conventional names for the separate instances are +upclientbin and upclientetc respectively. +

The upclient and upserver processes always mutually +authenticate, whether or not the data they pass is encrypted; they use +the key with the highest key version number in the +/usr/afs/etc/KeyFile file to construct a server ticket for mutual +authentication. +

Cautions +

Do not use the Update Server to distribute the contents of the +/usr/afs/etc directory if using the international edition of +AFS. The contents of this directory are sensitive and the international +edition of AFS does not include the encryption routines necessary for +encrypting files before transfer across the network. +

Options +

hostname +

Names either the cell's system control machine (if the requested +directory is /usr/afs/etc), or the binary distribution machine for +the local machine's CPU and operating system type (if the requested +directory is /usr/afs/bin). +

-crypt +

Requests the transfer of data from the upserver process in +encrypted form. With the United States edition of AFS, use this flag to +set the default explicitly. Provide this flag or the -crypt +flag, but not both. +

Note:

This flag is not available in the international edition of AFS. +

-clear +

Requests transfer of data from the upserver process in +unencrypted form. Use this flag to change from the default for the +United States edition of AFS. Provide this flag or the +-crypt flag, but not both. +

-t +

Specifies how often to check for changes in each specified directory, as a +number of seconds. If this argument is omitted, the default is 300 (5 +minutes). This argument determines the maximum amount of time it takes +for a change made on the source machine to propagate to this machine. +

-verbose +

Writes a trace of the upclient process's operations on the +standard output stream, which usually corresponds to the machine +console. Provide one, two, or three instances of the flag; each +additional instance generates increasingly numerous and detailed +messages. +

dir +

Names each directory to check for modified files. The conventional +choices are the following: +

/usr/afs/bin, in which case the recommended name for the +process (assigned with the -instance argument to the bos +create command) is upclientbin. The hostname +is the binary distribution machine for the local machine's system +type. Use the -clear flag be used for the +/usr/afs/bin directory, since binaries are not particularly +sensitive and encrypting them can take a long time. +
/usr/afs/etc, in which case the recommended name for the +process (assigned with the -instance argument to the bos +create command) is upclientetc. The hostname +is the cell's system control machine. Use the -crypt +flag for the /usr/afs/etc directory, since it contains the +KeyFile file and other data vital to cell security. +
As a reminder, do not use the Update Server to transfer the contents of the +/usr/afs/etc directory if using the international edition of +AFS. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following bos create command creates an +upclientbin process on the machine +fs4.abc.com that refers to the machine +fs1.abc.com as the source for the +/usr/afs/bin directory (thus fs1.abc.com +is the binary distribution machine for machines of +fs4.abc.com's type). The files in the +/usr/afs/bin directory are distributed every 120 seconds. +The command requests transfer in unencrypted form. +

   % bos create  -server fs4.abc.com -instance upclientbin -type simple   \
+                 -cmd "/usr/afs/bin/upclient fs1.abc.com -clear  \
+                 -t 120 /usr/afs/bin"
+   
+

Privilege Required +

Related Information +

upserver +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf241.htm b/doc/html/AdminReference/auarf241.htm new file mode 100644 index 0000000..a8791d6 --- /dev/null +++ b/doc/html/AdminReference/auarf241.htm @@ -0,0 +1,129 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

upserver

+ + + + + + +

Purpose +

Initializes the server portion of the Update Server +

Synopsis +

upserver [<directory>⁺]  [-crypt <directory>⁺]  [-clear <directory>⁺]
+         [-auth <directory>⁺]  [-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 upserver command initializes the server portion of the +Update Server (the upserver process). In the conventional +configuration, its binary file is located in the /usr/afs/bin +directory on a file server machine. +

The upserver command is not normally issued at the command shell +prompt but rather placed into a file server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a database server machine as the local superuser +root. +

The upserver command specifies which of the directories on the +local disk are eligible for distribution in response to requests from the +client portion of the Update Server (the upclient process) running +on other machines. If no directories are specified, the +upserver process distributes the contents of any directory on its +local disk. +

The upserver process can distribute a directory's contents +in encrypted or unencrypted form. By default, it does not use +encryption unless an upclient process requests it (this default is +equivalent to setting the -clear flag). When the +-crypt flag is provided, the upserver process only +fulfills requests for encrypted transfer. +

For the United States edition of AFS, using the -crypt flag +guarantees that the upserver process transfers a directory's +contents only in encrypted form. For the international edition, using +the -crypt flag completely blocks data transfer, because the +international edition of the upclient process cannot request +encrypted transfer (the upclient initialization command does not +include the -crypt flag). +

Cautions +

Options +

directory +: Names each directory to distribute in unencrypted form (because they +appear before the first -crypt or -clear flag on the +command line). If this argument is omitted, all directories on the +machine's local disk are eligible for distribution. +
-crypt +: Precedes a list of one or more directories that the upserver +process distributes only in encrypted form. +
-clear +: Precedes a list of one or more directories that the upserver +process distributes in unencrypted form unless the upclient process +requests them in encrypted form. Use this argument only if a list of +directories headed by the -crypt flag precedes it on the command +line. +
-auth +: Precedes a list of one or more directories which the upserver +process distributes using a form of encryption that is intermediate in +complexity and security between the unencrypted and encrypted levels set by +the -clear and -crypt arguments. Do not use this +argument, because the upclient process does not have a +corresponding argument that it can use to request data transfer at this +level. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example bos create command defines and starts an +upserver process on the host machine +fs1.abc.com. The last parameter (enclosed in +quotes) instructs the upserver process to distribute the contents +of the /usr/afs/bin directory in unencrypted form and the contents +of the /usr/afs/etc directory in encrypted form. +

   % bos create  -server fs1.abc.com -instance upserver -type simple   \
+                 -cmd "/usr/afs/bin/upserver /usr/afs/bin -crypt /usr/afs/etc"
+

Privilege Required +

Related Information +

upclient +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf242.htm b/doc/html/AdminReference/auarf242.htm new file mode 100644 index 0000000..631adf3 --- /dev/null +++ b/doc/html/AdminReference/auarf242.htm @@ -0,0 +1,110 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

uss

+ + + + + + + + + +

Purpose +

Introduction to the uss command suite +

Description +

The commands in the uss command suite help administrators to +create AFS user accounts more easily and efficiently. If uss +commands are not used, creating an account requires issuing at least six +separate commands to five different AFS servers. +

There are three main commands in the suite: +

The uss add command creates a single complete user account, +based on command line arguments and instructions in a template file. +
The uss bulk command creates multiple complete accounts at +once, based on command line arguments, instructions in a template file and a +bulk input file. +
the uss delete command removes most parts of a user +account. +

To obtain help, issue the uss apropos and uss help +commands. +

Options +

The following arguments and flags are available on many commands in the +uss suite. The reference page for each command also lists +them, but they are described here in greater detail. +

-admin <administrator to authenticate> +

Specifies the AFS user name under which to establish a connection to the +AFS server processes that administer the various parts of a user +account. If it is omitted, the connection is established under the +issuer's effective user ID (his or her identity in the local file +system). Even when this argument is included, UNIX commands that run +during the uss operation (for instance, the UNIX +/etc/chown command) run under the effective user ID. +

-cell <cell name> +

The value of the AFSCELL environment variable +
The local /usr/vice/etc/ThisCell file +

-dryrun +

Reports actions that the command interpreter needs to perform when +executing the uss operation, without actually performing +them. Include this flag to verify that the command produces the desired +account configuration. Combine it with the -verbose flag to +yield even more detailed information. Note that the output does not +necessarily reveal all possible problems that can prevent successful execution +of the command, especially those that result from transient server or network +outages. +

-help +

-skipauth +

Bypasses mutual authentication with the AFS Authentication Server, +allowing a site that uses Kerberos instead of the AFS Authentication Server to +substitute that form of authentication. +

Privilege Required +

The issuer of a uss command must have all the rights required +for performing the equivalent actions individually. See each +uss command's reference page. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf243.htm b/doc/html/AdminReference/auarf243.htm new file mode 100644 index 0000000..137c348 --- /dev/null +++ b/doc/html/AdminReference/auarf243.htm @@ -0,0 +1,291 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

uss add

+ + + + + + + + + + + + + + + + + + + +

Purpose +

Creates a user account +

Synopsis +

uss add -user <login name>  [-realname <full name in quotes>]
+        [-pass <initial password>]  
+        [-pwexpires <password expires in [0..254] days (0 => never)>]
+        [-server <FileServer for home volume>] 
+        [-partition <FileServer's disk partition for home volume>] 
+        [-mount <home directory mount point>]  
+        [-uid <uid to assign the user>]
+        [-template <pathname of template file>] 
+        [-verbose]  [-var <auxiliary argument pairs (Num val)>⁺] 
+        [-cell <cell name>]  [-admin <administrator to authenticate>]
+        [-dryrun]  [-skipauth]  [-overwrite]  [-help]
+   
+uss ad -us <login name>  [-r <full name in quotes>]   
+       [-pas <initial password>] 
+       [-pw <password expires in [0..254] days (0 => never)>]  
+       [-se <FileServer for home volume>] 
+       [-par <FileServer's disk partition for home volume>] 
+       [-m <home directory mount point>]  [-ui <uid to assign the user>]
+       [-t <pathname of template file>]  [-ve]  
+       [-va <auxiliary argument pairs (Num val)>⁺]  [-c <cell name>]
+       [-a <administrator to authenticate>]  [-d]  [-sk]  [-o]  [-h]
+

Description +

The uss add command creates entries in the Protection Database +and Authentication Database for the user name specified by the +-user argument. By default, the Protection Server +automatically allocates an AFS user ID (UID) for the new user; to specify +an alternate AFS UID, include the -uid argument. If a +password is provided with the -pass argument, it is stored as the +user's password in the Authentication Database after conversion into a +form suitable for use as an encryption key. Otherwise, the string +changeme is assigned as the user's initial password. +

The other results of the command depend on which instructions and which of +a defined set of variables appear in the template file specified with the +-template argument. Many of the command's arguments +supply a value for one of the defined variables, and failure to provide an +argument when the corresponding variable appears in the template file halts +the account creation process at the point where the command interpreter first +encounters the variable in the template file. +

To create multiple accounts with a single command, use the uss +bulk command. To delete accounts with a single command, use the +uss delete command. +

Options +

-user +

Names the user's Authentication Database and Protection Database +entries. It can include up to eight alphanumeric characters, but not +any of the following characters: : (colon), +@ (at-sign), . (period), space, or +newline. 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 variable in the template file: $USER. +

-realname +

Specifies the user's full name. If it contains spaces or +punctuation, surround it with double quotes. If not provided, it +defaults to the user name provided with the -user argument. +

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. +

-pass +

Corresponding variable in the template file: none. +

-pwexpires +

Corresponding variable in the template file: $PWEXPIRES. +

-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 variable in the template file: $SERVER. +

-partition +

Specifies the partition on which to create the user's volume; it +must be on the file server machine named by the -server +argument. Provide the complete partition name (for example +/vicepa) or one of the following abbreviated 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
+    
+

Corresponding variable in the template file: $PART. +

-mount +

Specifies the pathname for the user's home directory. Partial +pathnames are interpreted relative to the current working directory. +

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, it is best first to use the pts examine command to verify +that no existing account already has the desired AFS UID; it one does, +the account creation process terminates with an error. +

Corresponding variable in the template file: $UID. +

-template +

Specifies the pathname of the template file. If this argument is +omitted, the command interpreter searches the following directories in the +indicated order for a file called uss.template: +

The current working directory +
/afs/cellname/common/uss, where +cellname names the local cell +
/etc +

If the issuer provides a filename other than uss.template +but without a pathname, the command interpreter searches for it in the +indicated directories. If the issuer provides a full or partial +pathname, the command interpreter consults the specified file only; it +interprets partial pathnames relative to the current working directory. +

If the specified template file is empty (zero-length), the command creates +Protection and Authentication Database entries only. +

The uss Template File reference page details the file's +format. +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-var +

Specifies values for each of the number variables $1 through $9 that can +appear in the template file. Use the number variables to assign values +to variables in the uss template file that are not part of the +standard set. +

Corresponding variables in the template file: $1 through $9. +

For each instance of this argument, provide two parts in the indicated +order, separated by a space: +

The integer from the range 1 through 9 that matches +the variable in the template file. Do not precede it with a dollar +sign. +
A string of alphanumeric characters to assign as the value of the +variable. +

See the chapter on uss in the IBM AFS Administration +Guide for further explanation. +

-cell +

Specifies the cell in which to run the command. For more details, +see the introductory uss reference page. +

-admin +

Specifies the AFS user name under which to establish authenticated +connections to the AFS server processes that maintain the various components +of a user account. For more details, see the introductory +uss reference page. +

-dryrun +

Reports actions that the command interpreter needs to perform while +executing the command, without actually performing them. For more +details, see the introductory uss reference page. +

-skipauth +

Prevents authentication with the AFS Authentication Server, allowing a +site using Kerberos to substitute that form of authentication. +

-overwrite +

Overwrites any directories, files and links that exist in the file system +and for which there are definitions in D, E, +F, L, or S instructions in the template file +named by the -template argument. If this flag is omitted, +the command interpreter prompts once for confirmation that it is to overwrite +all such elements. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The combination of the following example uss add command and +V instruction in a template file called uss.tpl +creates Protection and Authentication Database entries named smith, +and a volume called user.smith with a quota of 2500 kilobyte +blocks, mounted at the pathname +/afs/abc.com/usr/smith. The access control list (ACL) +on the mount point grants smith all rights. +

The issuer of the uss add command provides only the template +file's name, not its complete pathname, because it resides in the current +working directory. The command and V instruction appear here +on two lines only for legibility; there are no line breaks in the actual +instruction or command. +

   V user.$USER $SERVER.abc.com /vice$PART $1   \
+       /afs/abc.com/usr/$USER $UID $USER all
+   
+   % uss add  -user smith -realname "John Smith" -pass js_pswd -server fs2   \
+              -partition b -template uss.tpl -var 1 2500
+   
+

Privilege Required +

The issuer (or the user named by the -admin argument) must +belong to the system:administrators group in the Protection +Database and must have the ADMIN flag turned on in his or her +Authentication Database entry. +

If the template contains a V instruction, the issuer must be +listed in the /usr/afs/etc/UserList file and must have at least +a (administer) and i (insert) +permissions on the ACL of the directory that houses the new mount +point. If the template file includes instructions for creating other +types of objects (directories, files or links), the issuer must have each +privilege necessary to create them. +

Related Information +

uss +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf244.htm b/doc/html/AdminReference/auarf244.htm new file mode 100644 index 0000000..734400f --- /dev/null +++ b/doc/html/AdminReference/auarf244.htm @@ -0,0 +1,70 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

uss apropos

+ + + +

Purpose +

Displays each help entry containing a keyword string. +

Synopsis +

uss apropos -topic <help string>  [-help]
+   
+uss ap -t <help string>  [-h]
+

Description +

The uss apropos command displays the first line of the online +help entry for any uss 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 uss 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 +uss command where the string specified by the -topic +argument is part of the command name or first line. +

Examples +

The following command lists all uss commands that include the +word create in their names or short descriptions: +

   % uss apropos create
+   add: create a new user
+   
+

Privilege Required +

None +

Related Information +

uss +

uss help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf245.htm b/doc/html/AdminReference/auarf245.htm new file mode 100644 index 0000000..77f6d4a --- /dev/null +++ b/doc/html/AdminReference/auarf245.htm @@ -0,0 +1,135 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

uss bulk

+ + + + + +

Purpose +

Executes multiple uss commands listed in a file +

Synopsis +

uss bulk -file <bulk input file>  [-template <pathname of template file>]
+         [-verbose]  [-cell <cell name>]  
+         [-admin <administrator to authenticate>] [-dryrun]  
+         [-skipauth]  [-overwrite]
+         [-pwexpires <password expires in [0..254] days (0 => never)>]  
+         [-pipe]  [-help]
+     
+uss b -f <bulk input file>  [-t <pathname of template file>]  [-v]  
+      [-c <cell name>]  [-a <administrator to authenticate>]  [-d]  [-s]  
+      [-o]  [-pw <password expires in [0..254] days (0 => never)>]  
+      [-pi]  [-h]
+

Description +

The uss bulk command executes the uss commands listed +in the bulk input file specified with the -file +argument. If the bulk input file includes add instructions +that reference a template file, then the -template argument is +required. +

To create a single account, use the uss add command. To +delete one or more accounts, use the uss delete command. +

Options +

-file +

Specifies the pathname of the bulk input file. Partial pathnames +are interpreted relative to the current working directory. For details +on the file's format, see uss Bulk Input File. +

-template +

Specifies the pathname of the template file for any uss add +commands that appear in the bulk input file. Partial pathnames are +interpreted relative to the current working directory. For details on +the file's format, see uss Template File. +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-cell +

Specifies the cell in which to run the command. For more details, +see the introductory uss reference page. +

-admin +

-dryrun +

Reports actions that the command interpreter needs to perform while +executing the command, without actually performing them. For more +details, see the introductory uss reference page. +

-skipauth +

Prevents authentication with the AFS Authentication Server, allowing a +site using Kerberos to substitute that form of authentication. +

-overwrite +

Overwrites any directories, files and links that exist in the file system +and for which there are also D, E, F, +L, or S instructions in a template file referenced by an +add instruction in the bulk input file. If this flag is +omitted, the command interpreter prompts, once for each add +instruction in the bulk input file, for confirmation that it should overwrite +such elements. Do not include this flag if the bulk input file does not +contain add instructions. +

-pwexpires +

Sets the number of days after a user's password is changed that it +remains valid, for each user named by an add instruction in the +bulk input file. 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). +

-pipe +

Suppresses the Authentication Server's prompt for the password of the +issuer or the user named by the -admin argument (the Authentication +Server always separately authenticates the creator of an entry in the +Authentication Database). Instead, the command interpreter accepts the +password via the standard input stream, as piped in from another +program. This enables the uss bulk command to run as part of +unattended batch jobs. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example command executes the instructions in the bulk input +file called new_students, which includes add +instructions that refer to the template file +student.template. Both files reside in the current +working directory. +

   % uss bulk new_students student.template
+   
+

Privilege Required +

The issuer (or the user named by the -admin argument) must have +the privileges necessary to run the commands that correspond to instructions +in the bulk input file. +

Related Information +

uss +

uss delete +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf246.htm b/doc/html/AdminReference/auarf246.htm new file mode 100644 index 0000000..589170d --- /dev/null +++ b/doc/html/AdminReference/auarf246.htm @@ -0,0 +1,132 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

uss delete

+ + + + + + + + + + +

Purpose +

Deletes a user account +

Synopsis +

uss delete -user <login name>  [-mountpoint <mountpoint for user's volume>] 
+           [-savevolume]  [-verbose]  [-cell <cell name>]  
+           [-admin <administrator to authenticate>]  [-dryrun]  
+           [-skipauth]  [-help]
+    
+uss d -u <login name>  [-m <mountpoint for user's volume>]  [-sa]  [-v]
+      [-c <cell name>]  -a <administrator to authenticate>]  
+      [-d]  [-sk]  [-h]
+

Description +

The uss delete command removes the Authentication Database and +Protection Database entries for the user named by -user +argument. In addition, it can remove the user's home volume and +associated VLDB entry, a mount point for the volume or both, depending on +whether the -mountpoint and -savevolume options are +provided. +

To remove both the volume and mount point, use the -mountpoint +argument to name the user's home directory. It is best to create a +tape backup of a volume before deleting it. Note that other mount +points for the volume are not removed, if they exist. +
To remove the mount point only, provide both the -mountpoint +and -savevolume options. +
To preserve both the volume and mount point, omit the +-mountpoint argument (or both it and the -savevolume +flag). +

Options +

-user +

Names the entry to delete from the Protection and Authentication +Databases. +

-mountpoint +

Specifies the pathname to the user's home directory, which is deleted +from the filespace. By default, the volume referenced by the mount +point is also removed from the file server machine that houses it, along with +its Volume Location Database (VLDB) entry. To retain the volume and +VLDB entry, include the -savevolume flag. Partial pathnames +are interpreted relative to the current working directory. +

Specify the read/write path to the mount point, to avoid the failure that +results from attempting to remove a mount point from 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 +fs mkmount reference page. +

-savevolume +

Preserves the user's volume and VLDB entry. +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-cell +

Specifies the cell in which to run the command. For more details, +see the introductory uss reference page. +

-admin +

-dryrun +

Reports actions that the command interpreter needs to perform while +executing the command, without actually performing them. For more +details, see the introductory uss reference page. +

-skipauth +

Prevents authentication with the AFS Authentication Server, allowing a +site using Kerberos to substitute that form of authentication. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command removes smith's user account from the +abc.com cell. The -savevolume argument +retains the user.smith volume on its file server +machine. +

   % uss delete smith -mountpoint /afs/abc.com/usr/smith -savevolume
+   
+

Privilege Required +

The issuer (or the user named by -admin argument) must belong to +the system:administrators group in the Protection Database, +must have the ADMIN flag turned on in his or her Authentication +Database entry, and must have at least a (administer) +and d (delete) permissions on the access control list +(ACL) of the mount point's parent directory. If the +-savevolume flag is not included, the issuer must also be listed in +the /usr/afs/etc/UserList file. +

Related Information +

uss +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf247.htm b/doc/html/AdminReference/auarf247.htm new file mode 100644 index 0000000..6a9769d --- /dev/null +++ b/doc/html/AdminReference/auarf247.htm @@ -0,0 +1,87 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

uss help

+ + + +

Purpose +

Displays the syntax of specified uss commands or lists +functional descriptions of all uss commands +

Synopsis +

uss help [-topic <help string>⁺]  [-help]
+    
+uss h [-t <help string>⁺]  [-h]
+

Description +

The uss help command displays the complete online help entry +(short description and syntax statement) for each command operation code +specified by the -topic argument. If the -topic +argument is omitted, the output includes the first line (name and short +description) of the online help entry for every uss command. +

To list every uss command whose name or short description +includes a specified keyword, use the uss apropos command. +

Options +

-topic +: Indicates each command for which to display the complete online help +entry. Omit the uss part of the command name, providing only +the operation code (for example, specify bulk, not uss +bulk). If this argument is omitted, the output briefly describes +every uss command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each uss command consists of the +following two or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following command displays the online help entry for the uss +bulk command: +

   % uss help bulk
+   uss bulk: bulk input mode
+   Usage: uss bulk -file <bulk input file> [-template <pathname 
+   of template file>] [-verbose] [-cell <cell name>] [-admin 
+   <administrator to authenticate>] [-dryrun] [-skipauth] [-overwrite] 
+   [-pwexpires <password expires in [0..254] days (0 => never)>] [-pipe] 
+   [-help]
+   
+

Privilege Required +

None +

Related Information +

uss +

uss apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf248.htm b/doc/html/AdminReference/auarf248.htm new file mode 100644 index 0000000..47ed124 --- /dev/null +++ b/doc/html/AdminReference/auarf248.htm @@ -0,0 +1,91 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vldb_check

+ + + +

Purpose +

Checks the integrity of the VLDB +

Synopsis +

vldb_check -database <vldb_file>  [-uheader]  [-vheader]  [-servers]  
+           [-entries]  [-verbose]  [-help]
+   
+vldb_check -d <vldb_file>  [-u]  [-vh]  [-s]  [-e]  [-ve]  [-h]
+

Description +

The vldb_check command checks the integrity of the Volume +Location Database (VLDB), reporting any errors or corruption it finds. +If there are problems, do not issue any vos commands until the +database is repaired. +

Cautions +

The results can be unpredictable if the Volume Location (VL) Server makes +changes to the VLDB while this command is running. Use the bos +shutdown command to shutdown the local vlserver process +before running this command, or before creating a second copy of the +vldb.DB0 file (with a different name) on which to run the +command. +

Options +

-database +: Names the VLDB (copy of the vldb.DB0 file) to +check. If the current working directory is not the location of the +file, provide a pathname, either full or relative to the current working +directory. +
-uheader +: Displays information which Ubik maintains in the database's +header. +
-pheader +: Displays information which the VL Server maintains in the database's +header. +
-servers +: Outputs the server entries from the VLDB, which list the IP addresses +registered for each file server machine in the cell. +
-entries +: Outputs every volume entry in the database. The information +includes the volume's name and the volume ID number for each of its +versions. +
-verbose +: Reports additional information about the database, including the number of +entries for each type of volume. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

bos shutdown +

vlserver +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf249.htm b/doc/html/AdminReference/auarf249.htm new file mode 100644 index 0000000..57d6b12 --- /dev/null +++ b/doc/html/AdminReference/auarf249.htm @@ -0,0 +1,114 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vlserver

+ + + + +

Purpose +

Initializes the Volume Location Server +

Synopsis +

vlserver [-p <lwp processes>]  [-nojumbo]  
+         [-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 vlserver command initializes the Volume Location (VL) +Server, which runs on every database server machine. In the +conventional configuration, its binary file is located in the +/usr/afs/bin directory on a file server machine. +

The vlserver command is not normally issued at the command shell +prompt but rather placed into a file server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a database server machine as the local superuser +root. +

As it initializes, the VL Server process creates the two files that +constitute the Volume Location Database (VLDB), vldb.DB0 and +vldb.DBSYS1, in the /usr/afs/db directory if they +do not already exist. Use the commands in the vos suite to +administer the database. +

The VL Server maintains the record of volume locations in the Volume +Location Database (VLDB). When the Cache Manager fills a file request +from an application program, it first contacts the VL Server to learn which +file server machine currently houses the volume that contains the file. +The Cache Manager then requests the file from the File Server process running +on that file server machine. +

The VL Server records a trace of its activity in the +/usr/afs/logs/VLLog file. Use the bos getlog +command to display the contents of the file. By default, it records on +a minimal number of messages. For instructions on increasing the amount +of logging, see the VLLog reference page. +

By default, the VL Server runs nine lightweight processes (LWPs). To +change the number, use the -p argument. +

Options +

-p +: Sets the number of server lightweight processes (LWPs) to run. +Provide an integer between 4 and 16. The default +is 9. +
-nojumbo +: Prohibits the server from sending or receiving jumbograms. A +jumbogram is a large-size packet composed of 2 to 4 normal Rx data packets +that share the same header. The VL Server uses jumbograms by default, +but some routers are not capable of properly breaking the jumbogram into +smaller packets and reassembling them. +
-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 following bos create command creates a vlserver +process on the machine fs2.abc.com that uses six +lightweight processes. Type the command on a single line: +

   % bos create -server fs2.abc.com -instance vlserver -type simple  \
+                -cmd "/usr/afs/bin/vlserver -p 6"
+

Privilege Required +

Related Information +

VLLog +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf250.htm b/doc/html/AdminReference/auarf250.htm new file mode 100644 index 0000000..a77ed5b --- /dev/null +++ b/doc/html/AdminReference/auarf250.htm @@ -0,0 +1,115 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

volinfo

+ + +

Purpose +

Produces detailed statistics about one or more volume headers and the +partition that houses them +

Synopsis +

volinfo [-online]  [-vnode]  [-date]  [-inode] [-itime]  
+        [-part  <AFS partition name (default current partition)>⁺]   
+        [-volumeid <Volume id>⁺]  [-header]  [-sizeOnly]  [-fixheader]  
+        [-saveinodes]  [-orphaned]  [-help]
+

Description +

The volinfo command displays detailed statistics about one or +more volume headers and the partition that houses them. The command +must be issued on a file server machine and by default produces output for +every volume on every AFS server partition on the machine. To display +output for the volumes on one partition only, include the -part +argument. To display output for one volume only, include the +-volumeid argument. +

Options +

-online +: Is nonoperational. +
-vnode +: Displays a table for each volume which lists the large (directory) and +small (file) vnodes in it, in addition to the default output. +
-date +: When combined with the -vnode flag, adds the +ServerModTime field to each vnode entry in the large vnode and +small vnode tables, reporting its most recent modification time. +
-inode +: When combined with the -vnode flag, adds the inode +field to each vnode entry in the large vnode and small vnode tables, reporting +the associated inode number. +
-itime +: When combined with the -vnode flag, displays a change, +modification, and access timestamp for each of the large vnode and small vnode +tables. +
-part +: Specifies the partition that houses each volume for which to produce +output. Use the format /vicepxx, where xx +is one or two lowercase letters. This argument can be omitted if the +current working directory is the mount location for an AFS server +partition; it is not the mount location for an AFS server partition, the +command produces output for every volume on all local AFS server +partitions. +
-volumeid +: Specifies the ID number of one volume for which to produce output. +The -part argument must be provided along with this one unless the +current working directory is the mount location for the AFS server partition +that houses the volume. +
-header +: Displays statistics about the volume header of each volume, in addition to +the default output. +
-sizeOnly +: Displays a single line of output for each volume, reporting the size of +various structures associated with it. The default output is suppressed +and any flags that modify it (such as -vnode) are ignored. +
-fixheader +: Repairs damaged inodes in each volume if possible. If there are +any, it reports the action it is taking to repair them. Otherwise, it +produces no output in addition to the default output. +
-saveinodes +: Creates a file in the current working directory for each inode in each +volume. Each file is called +TmpInode.vnode_number and contains the inode's +contents. The default output is suppressed and any flags that modify it +(such as -vnode) are ignored. +
-orphaned +: Displays a large vnode and small vnode table for each volume, which lists +only orphaned vnodes (vnodes that have no parent). If there are none, +the tables are empty (only the headers appear). +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

By default, the command produces several line of statistics for each +volume. Adding other options produces or substitutes additional +information as described in the preceding Options section of this +reference page. The output is intended for debugging purposes and is +meaningful to someone familiar with the internal structure of volume +headers. +

Privilege Required +

The issuer must be logged in as the local superuser root. +

Related Information +

volserver +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf251.htm b/doc/html/AdminReference/auarf251.htm new file mode 100644 index 0000000..5e77582 --- /dev/null +++ b/doc/html/AdminReference/auarf251.htm @@ -0,0 +1,105 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

volserver

+ + + +

Purpose +

Initializes the Volume Server component of the fs process +

Synopsis +

volserver [-log]  [-p <number of processes>]  
+          [-udpsize <size of socket buffer in bytes>]  
+          [-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 volserver command initializes the Volume Server component of +the fs process. In the conventional configuration, its +binary file is located in the /usr/afs/bin directory on a file +server machine. +

The volserver command is not normally issued at the command +shell prompt but rather placed into a file server machine's +/usr/afs/local/BosConfig file with the bos create +command. If it is ever issued at the command shell prompt, the issuer +must be logged onto a database server machine as the local superuser +root. +

The Volume Server records a trace of its activity in the +/usr/afs/logs/VolserLog file. Use the bos getlog +command to display the contents of the file. +

The Volume Server processes the vos commands that administrators +use to create, delete, move, and replicate volumes, as well as prepare them +for archiving to tape or other media. +

By default, the VL Server runs nine lightweight processes (LWPs). To +change the number, use the -p argument. +

Options +

-log +: Records in the /usr/afs/logs/VolserLog file the names of all +users who successfully initiate a vos command. The Volume +Server also records any file removals that result from issuing the vos +release command with the -f flag. +
-p +: Sets the number of server lightweight processes (LWPs) to run. +Provide an integer between 4 and 16. The default +is 9. +
-udpsize +: Sets the size of the UDP buffer, which is 64 KB by default. Provide +a positive integer, preferably larger than the default. +
-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 following bos create command creates a volserver +process on the machine fs2.abc.com: +

   % bos create -server fs2.abc.com -instance volserver -type simple   \
+                 -cmd /usr/afs/bin/volserver 
+

Privilege Required +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf252.htm b/doc/html/AdminReference/auarf252.htm new file mode 100644 index 0000000..fa3a98f --- /dev/null +++ b/doc/html/AdminReference/auarf252.htm @@ -0,0 +1,243 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos

+ + + + + + + + + + + + + + + + + + +

Purpose +

Introduction to the vos command suite +

Description +

The commands in the vos command suite are the administrative +interface to the Volume Server and Volume Location (VL) Server. System +administrators use vos commands to create, move, delete, replicate, +back up and examine volumes, among other operations. The VL Server +automatically records in the Volume Location Database (VLDB) changes in volume +status and location that result from vos commands. +

The operations invoked by most vos commands are idempotent, +meaning that if an operation is interrupted by a network, server machine, or +process outage, then a subsequent attempt at the same operation continues from +the interruption point, rather than starting over at the beginning of the +operation. Before executing a command, the Volume and VL Servers check +the current state of the volumes and VLDB records to be altered by the +command. If they are already in the desired end state (or a consistent +intermediate state), there is no need to repeat the internal steps that +brought them there. Idempotency does not apply if the command issuer +explicitly interrupts the operation with the <Ctrl-c> command or +another interrupt signal. In that case, the volume is left locked and +the administrator must use the vos unlock command to unlock it +before proceeding. +

It is important that the VLDB accurately indicate the status of the volumes +on file server machines at all times. The reference pages for the files +vldb.DB0 and +Vvol_ID.vol describe the information +recorded in the VLDB and volume headers, respectively. If a +vos command changes volume status, it automatically records the +change in the corresponding VLDB entry. The most common cause of +discrepancies between the VLDB and volume status on file server machines is +interrupted operations; to restore consistency, use the vos +syncserv and vos syncvldb commands. +

There are several categories of commands in the vos command +suite: +

Commands to create, move, and rename volumes: vos backup, +vos backupsys, vos create, vos move, and +vos rename +
Commands to remove VLDB volume records or volumes or both: vos +delentry, vos remove, and vos zap +
Commands to edit or display VLDB server entries: vos +changeaddr and vos listaddrs +
Commands to create and restore dump files: vos dump and +vos restore +
Commands to administer replicated volumes: vos addsite, +vos release, and vos remsite +
Commands to display VLDB records, volume headers, or both: vos +examine, vos listvldb, and vos listvol +
Commands to display information about partitions that house volumes: +vos listpart and vos partinfo +
Commands to restore consistency between the VLDB and volume headers: +vos syncserv and vos syncvldb +
Commands to lock and unlock VLDB entries: vos lock, +vos unlock, and vos unlockvldb +
A command to report Volume Server status: vos status +
Commands to obtain help: vos apropos and vos +help +

Options +

The following arguments and flags are available on many commands in the +bos suite. The reference page for each command also lists +them, but they are described here in greater detail. +

-cell <cell name> +

The value of the AFSCELL environment variable +
The local /usr/vice/etc/ThisCell file +

-help +

-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 vos command interpreter presents the ticket, which +never expires, to the Volume Server and VL Server during mutual +authentication. +

-noauth +

Establishes an unauthenticated connection to the Volume Server and VL +Server, in which the servers treat the issuer as the unprivileged user +anonymous. It is useful only when authorization checking is +disabled on the server machine (during the installation of a file server +machine or when the bos setauth command has been used during other +unusual circumstances). In normal circumstances, the servers allow only +privileged users to issue commands that change the status of a volume or VLDB +record, and refuses to perform such an action even if the -noauth +flag is provided. Do not combine the -noauth and +-localauth flags. +

-partition <partition name> +

Identifies the AFS server partition on a file server machine that houses, +or is to house, the volumes of interest, or about which to list +information. The vos command interpreter accepts any of the +following four name formats: +

   /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
+    
+

The -frompartition and -topartition arguments to the +vos move command also accept this notation. +

-server <machine name> +

Identifies the file server machine that houses, or is to house, the +volumes or AFS server partitions of interest. Provide the +machine's IP address in dotted decimal format, its fully qualified host +name (for example, fs1.abc.com), or the shortest +abbreviated form of its host name that distinguishes it from other +machines. Successful use of an abbreviated form depends on the +availability of a name resolution service (such as the Domain Name Service or +a local host table) at the time the command is issued. +

The -fromserver and -toserver arguments to the +vos move command also accept these name formats. +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

Privilege Required +

To issue most vos commands, the issuer must be listed in the +/usr/afs/etc/UserList file on each server machine that houses or is +to house an affected volume, and on each database server machine. The +most predictable performance results if all database server and file server +machines in the cell share a common UserList file. +Alternatively, if the -localauth flag is included, the issuer must +be logged on to a server machine as the local superuser +root. +

To issue a vos command that only displays information, no +privilege is required. +

Related Information +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf253.htm b/doc/html/AdminReference/auarf253.htm new file mode 100644 index 0000000..0a5d15f --- /dev/null +++ b/doc/html/AdminReference/auarf253.htm @@ -0,0 +1,120 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos addsite

+ + + + + + +

Purpose +

Adds a read-only site definition to a volume's VLDB entry +

Synopsis +

vos addsite -server <machine name for new site>
+            -partition <partition name for new site>
+            -id <volume name or ID>  [-cell <cell name>]  
+            [-noauth]  [-localauth]  [-verbose]  [-help]
+   
+vos ad -s <machine name for new site>  -p <partition name for new site>
+       -i <volume name or ID>  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos addsite command defines a new read-only site (partition +on a file server machine, specified by the -server and +-partition arguments) in the Volume Location Database (VLDB) entry +of the read/write volume named by the -id argument. When the +vos release command is next issued against the read/write volume, a +read-only copy of it is distributed to all of the read-only sites, including +the newly defined one. +

Cautions +

A volume's VLDB entry accommodates a maximum number of site +definitions, as defined in the IBM AFS Release Notes. The +site housing the read/write and backup versions of the volume counts as one +site, and each read-only site counts as an additional site (even the read-only +site defined on the same file server machine and partition as the read/write +site counts as a separate site). The limit in the VLDB entry +effectively determines the maximum number of copies of the volume that are +available to AFS clients. +

Attempts to create additional sites by using this command fail with an +error. +

Options +

-server +: Identifies the file server machine where the read-only volume is to +reside. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +
-partition +: Identifies the partition where the read-only volume is to reside, on the +file server machine named by the -server argument. Provide +the partition's complete name with preceding slash (for example, +/vicepa) or use one of the three acceptable abbreviated +forms. For details, see the introductory reference page for the +vos command suite. +
-id +: Specifies either the complete name or volume ID number of the read/write +source volume. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example, appropriate in the State University cell, defines a +read-only site for the cell's root.afs volume. +

   % vos addsite -server sv7.stateu.edu -partition /vicepb -id root.afs
+   
+

Privilege Required +

The issuer must be listed in the /usr/afs/etc/UserList file on +the machine specified with the -server argument and on each +database server machine. If the -localauth flag is included, +the issuer must instead be logged on to a server machine as the local +superuser root. +

Related Information +

vos +

vos release +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf254.htm b/doc/html/AdminReference/auarf254.htm new file mode 100644 index 0000000..9c46bbe --- /dev/null +++ b/doc/html/AdminReference/auarf254.htm @@ -0,0 +1,72 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos apropos

+ + + +

Purpose +

Displays each help entry containing a keyword string +

Synopsis +

vos apropos -topic <help string>  [-help]
+    
+vos ap -t <help string>  [-h]
+

Description +

The vos apropos command displays the first line of the online +help entry for any vos 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 vos help +command. +

Options +

-topic +: Specifies the keyword string to match. Use lowercase letters only, +except for the acronym VLDB. 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 +vos command where the string specified with the -topic +argument is part of the command name or first line. +

Examples +

The following command displays all vos commands that include the +word lock in their names or short descriptions: +

   % vos apropos lock
+   lock: lock VLDB entry for a volume
+   unlock: release lock on VLDB entry for a volume
+   unlockvldb: unlock all the locked entries in the VLDB
+   
+

Privilege Required +

None +

Related Information +

vos +

vos help +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf255.htm b/doc/html/AdminReference/auarf255.htm new file mode 100644 index 0000000..54d055e --- /dev/null +++ b/doc/html/AdminReference/auarf255.htm @@ -0,0 +1,106 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos backup

+ + + + + + + + + +

Purpose +

Creates a backup volume for a single read/write volume +

Synopsis +

 
+vos backup -id <volume name or ID>  [-cell <cell name>]  [-noauth]  
+           [-localauth]  [-verbose]  [-help]
+   
+vos backup -i <volume name or ID>  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos backup command clones the indicated read/write volume to +create a backup version, placing it at the same site as the read/write +version. The backup volume's name is the same as the read/write +source's with the addition of the .backup +extension. Its volume ID number is the one allocated for it in the +Volume Location Database (VLDB) when the read/write source was created with +the vos create command. If a backup version already exists, +the new clone replaces it. +

To create a backup version of multiple volumes, use the vos +backupsys command. +

Options +

-id +: Specifies either the complete name or volume ID number of the read/write +source volume. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The following message confirms that the command succeeded: +

   Created backup volume for volume name
+   
+

Examples +

The following example creates a backup version of the volume +user.smith. +

   % vos backup user.smith
+   Created backup volume for user.smith
+   
+

Privilege Required +

Related Information +

vos +

vos backupsys +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf256.htm b/doc/html/AdminReference/auarf256.htm new file mode 100644 index 0000000..316a550 --- /dev/null +++ b/doc/html/AdminReference/auarf256.htm @@ -0,0 +1,270 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos backupsys

+ + + + + + + +

Purpose +

Creates a backup volume for several read/write volumes +

Synopsis +

vos backupsys [-prefix <common prefix on volume(s)>⁺]  
+              [-server <machine name>]  [-partition <partition name>]  
+              [-exclude]  [-xprefix <negative prefix on volume(s)>⁺] 
+              [-dryrun]  [-cell <cell name>]  [-noauth]  [-localauth]
+              [-verbose]  [-help] 
+    
+vos backups [-pr <common prefix on volume(s)>⁺]  [-s <machine name>] 
+            [-pa <partition name>]  [-e]  [-x <negative prefix on volume(s)>⁺]  
+            [-d]  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos backupsys command clones each indicated read/write +volume to create a backup version, placing each clone at the same site as its +read/write source version. It assigns each clone the same name as the +read/write source, adding a .backup extension. It +assigns the volume ID number already allocated for the backup version in the +Volume Location Database (VLDB). If a backup version already exists for +a given volume, the new clone replaces it. +

To clone every read/write volume at the specified location whose name +includes one of a set of specified character strings (for example, begins with +user. or includes the string afs), use the +-prefix argument or combine the -xprefix and +-exclude options. +
To clone every read/write volume at the specified location except those +whose name includes one of a set of specified character strings, use the +-xprefix argument or combine the -prefix and +-exclude options. +
To clone every read/write volume at the specified location whose name +includes one of one of a set of specified character strings, except those +whose names include one of a different set of specified character strings, +combine the -prefix and -xprefix arguments. The +command creates a list of all volumes that match the -prefix +argument and then removes from the list the volumes that match the +-xprefix argument. For effective results, the strings +specified by the -xprefix argument must designate a subset of the +volumes specified by the -prefix argument. +
If the -exclude flag is combined with the -prefix and +-xprefix arguments, the command creates a list of all volumes that +do not match the -prefix argument and then adds to the list any +volumes that match the -xprefix argument. As when the +-exclude flag is not used, the result is effective only if the +strings specified by the -xprefix argument designate a subset of +the volumes specified by the -prefix argument. +

The -prefix and -xprefix arguments both accept +multiple values, which can be used to define disjoint groups of +volumes. Each value can be one of two types: +

A simple character string, which matches volumes whose name begin with the +string. All characters are interpreted literally (that is, characters +that potentially have special meaning to the command shell, such as the +period, have only their literal meaning). +
A regular expression, which matches volumes whose names contain the +expressions. Place a caret ( ^ ) at the +beginning of the expression, and enclose the entire string in single quotes +(' '). Explaining regular +expressions is outside the scope of this reference page; see the UNIX +manual page for regexp(5) or (for a brief introduction) the +backup addvolentry reference page in this document. As an +example, the following expression matches volumes that have the string +aix anywhere in their names: +
```
   -prefix  '^.*aix'
+
```
+

This command can be used to clone a single read/write volume; specify +its complete name as the -prefix argument. However, it is +more efficient to use the vos backup command, which employs a more +streamlined technique for finding a single volume. +

Options +

-prefix +

Specifies one or more simple character strings or regular expressions of +any length; a volume whose name includes the string is placed on the set +of volumes to be cloned. Include field separators (such as periods) if +appropriate. This argument can be combined with any combination of the +-server, -partition, -exclude, and +-xprefix options. +

-server +

Identifies the file server machine where each read/write source volume +resides. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +

This argument can be combined with any combination of the +-prefix, -partition, -exclude, and +-xprefix options. +

-partition +

Identifies the partition where each read/write source volume +resides. Provide the partition's complete name with preceding +slash (for example, /vicepa) or use one of the three acceptable +abbreviated forms. For details, see the introductory reference page for +the vos command suite. +

This argument can be combined with any combination of the +-prefix, -server, -exclude, and +-xprefix options. +

-exclude +

Reverses the meaning of the -prefix or -xprefix +argument. This flag can be combined with any combination of the +-prefix, -server, -partition, and +-xprefix options. +

-xprefix +

Specifies a simple character string or regular expression of any +length; a volume whose name includes the string is removed from the set +of volumes to be cloned. Include field separators (such as periods) if +appropriate. This argument can be combined with any combination of the +-prefix, -server, -partition, and +-exclude options. +

-dryrun +

Displays on the standard output stream a list of the volumes to be cloned, +without actually cloning them. +

-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 vos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +

-localauth +

Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The command generates the following messages on the standard output stream +to confirm that the operation was successful: +

   done
+   Total volumes backed up: number_cloned; failed to backup: failures
+

If the -dryrun flag is included, a list of the volumes to be +backed up precedes the standard confirmation messages. +

If the -verbose flag is included but not the -dryrun +flag, the following messages appear for each volume. The output +concludes with the standard confirmation messages. +

   Creating backup volume for volume_name on date/time
+   {Recloning backup volume | Creating a new backup clone} backup_volumeID . . .done
+

If both the -dryrun and -verbose flags are included, +the output begins with a statement summarizing the criteria being used to +select the volumes, followed by a list of the volumes and the standard +confirmation messages. The format of the criteria summary statement +depends on which other options are provided: +

If only the -prefix argument is provided, or the +-xprefix and -exclude options are combined: +
```
   Would have backed up volumes which are prefixed with string [orstring] . .
+
```
+
If only the -xprefix argument is provided, or the +-prefix and -exclude options are combined: +
```
   Would have backed up volumes which are not prefixed with string [norstring] . .
+
```
+

If the -prefix and -xprefix arguments are +combined: +

   Would have backed up volumes which are prefixed with string [orstring]  \
+      removing those which are prefixed with  x_string [orx_string] . .
+

If the -prefix, -xprefix, and -exclude +options are provided: +

   Would have backed up volumes which are not prefixed with string [norstring]  \
+      adding those which are prefixed with  x_string [orx_string] . .
+

Examples +

The following example creates a backup version of every read/write volume +listed in the cell's VLDB whose name begins with the string +user. +

   % vos backupsys -prefix user
+   
+

The following example, appropriate in the ABC Corporation cell, creates a +backup version of every read/write volume on the file server machine +fs3.abc.com. +

   % vos backupsys -server fs3.abc.com
+   
+

The following example, appropriate in the State University cell, creates a +backup version of every read/write volume on the file server machine +db1.stateu.edu except those whose name includes the +string temp. +

   % vos backupsys  -server db1.stateu.edu -prefix '^.*temp'
+   
+

The following example creates a backup version of every volume listed in +the cell's VLDB, excluding those whose names contain the string +source, but including those whose names contain the string +source.current. +

   % vos backupsys  -prefix '^.*source' -exclude -xprefix '^.*source\.current'
+   
+

Privilege Required +

Related Information +

backup addvolentry +

vos +

vos backup +

UNIX manual page for regexp(5) +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf257.htm b/doc/html/AdminReference/auarf257.htm new file mode 100644 index 0000000..a9c20b4 --- /dev/null +++ b/doc/html/AdminReference/auarf257.htm @@ -0,0 +1,129 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos changeaddr

+ + +

Purpose +

Changes or removes a file server machine's entry in the VLDB +

Synopsis +

vos changeaddr -oldaddr <original IP address>  [-newaddr <new IP address>] 
+               [-remove]  [-cell <cell name>]  [-noauth]  [-localauth]  
+               [-verbose]  [-help]
+    
+vos ch -o <original IP address>  [-ne <new IP address>]  [-r]  
+       [-c <cell name>]  [-no]  [-l]  [-v]  [-h]
+

Description +

The vos changeaddr command removes a server entry from the +Volume Location Database (VLDB) when the -remove flag is combined +with the -oldaddr argument. There must be no VLDB entries +that list the machine as a site for any version of a volume (if necessary, use +the vos move or vos remove command to more or remove +volumes). It is appropriate to remove a VLDB server entry when removing +the corresponding file server machine from service; this is the only +recommended use of the command. +

To display all VLDB server entries, use the vos listaddrs +command. +

Cautions +

Combining the command's -oldaddr and -newaddr +arguments is no longer the appropriate way to change the IP address registered +for a file server machine. Furthermore, if a machine is multihomed and +its server entry includes several addresses, then the address specified with +the -newaddr argument replaces all of the addresses currently +listed in the server entry that includes the address specified by the +-oldaddr argument. This effectively makes the machine +single-homed with respect to AFS operations, which is probably not the desired +result. +

The recommended method for changing the IP addresses in a server entry is +instead to restart the fs process group (which includes the File +Server) after using the utilities provided by the operating system to +reconfigure the machine's network interfaces. For a description of +how the File Server constructs and registers a list of its network interfaces +in the VLDB, see the reference page for the sysid file. +

If, counter to recommended usage, the command is used to change the IP +address in a server entry, it does not also change the names of machine +entries in the Protection Database. Operations fail when they refer to +a protection group that has an obsolete IP address in it. Use the +pts rename command to change the names of machine entries that +correspond to the addresses changed with this command. Changing the +address of a database server machine also requires updating the client and +server versions of the CellServDB file on every machine. +

Options +

-oldaddr +: Specifies the IP address currently registered for the file server machine +in the VLDB server entry. If there are multiple addresses registered +for a multihomed machine, use any of them to identify the server entry. +
-newaddr +: Specifies the new IP address that replaces all currently registered +addresses. +
-remove +: Removes from the VLDB the server entry that includes the address specified +by the -oldaddr argument. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command removes the VLDB server entry that includes the IP +address 192.12.107.214. +

   % vos changeaddr -oldaddr 192.12.107.214 -remove
+   
+

Privilege Required +

Issuer must be listed in the /usr/afs/etc/UserList file on the +machine specified with the -oldaddr argument and on each database +server machine. +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf258.htm b/doc/html/AdminReference/auarf258.htm new file mode 100644 index 0000000..7a1e121 --- /dev/null +++ b/doc/html/AdminReference/auarf258.htm @@ -0,0 +1,165 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos create

+ + + + + + + + + + + + + + + + + + +

Purpose +

Creates a read/write volume and associated VLDB entry +

Synopsis +

vos create -server <machine name>  -partition <partition name>
+           -name <volume name>  [-maxquota <initial quota (KB)>]  
+           [-cell <cell name>]  [-noauth]  [-localauth]  [-verbose]  [-help]
+    
+vos cr -s <machine name>  -p <partition name>  -na <volume name>
+       [-m <initial quota (KB)>]  [-c <cell name>]  [-no]  [-l]  [-v]  [-h]
+

Description +

The vos create command creates a read/write volume with the name +specified by the -name argument at the site specified by the +-server and -partition arguments. In addition, +the command allocates or sets the following: +

Volume ID numbers for the read/write volume and its associated read-only +and backup volumes (this command does not actually create the latter two types +of volume). A volume ID number is an identification number guaranteed +to be unique within a cell. + + + + + + +
An access control list (ACL) associated with the volume's root +directory, which takes the same name as volume's mount point when the +volume is mounted with the fs mkmount command. An entry that +grants all seven permissions to the members of the +system:administrators group is automatically placed on the +ACL. (In addition, the File Server by default always implicitly grants +the l (lookup) and a (administer) +permissions on every ACL to members of the +system:administrators group, even when the group does not +appear on an ACL; use the -implicit argument to the +fileserver initialization command to alter the set of rights on a +server-by-server basis if desired.) +
The volume's space quota, set to 5000 kilobyte blocks by +default. Use the -maxquota argument to specify a different +quota, or use the fs setquota command to change the volume's +quota after mounting the volume with the fs mkmount command. +

The volume is empty when created. To access it via the Cache +Manager, mount it in the file space by using the fs mkmount +command. +

Options +

-server +: Identifies the file server machine on which to create the read/write +volume. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +
-partition +: Identifies the partition on which to create the read/write volume, on the +file server machine specified by the -server argument. +Provide the partition's complete name with preceding slash (for example, +/vicepa) or use one of the three acceptable abbreviated +forms. For details, see the introductory reference page for the +vos command suite. +
-name +: Specifies a name for the read/write volume. The maximum length is +22 characters, which can include any alphanumeric or punctuation +character. By convention, periods separate the fields in a name. +Do not apply the .backup or .readonly +extension to a read/write volume name; they are reserved for the Volume +Server to add to the read/write name when creating those backup and read-only +volumes respectively. +
-maxquota +: Specifies the maximum amount of disk space the volume can use, as a number +of kilobyte blocks (a value of 1024 is one megabyte). The +value 0 (zero) grants an unlimited quota, but the size of the disk +partition that houses the volume places an absolute limit on its size. +If this argument is omitted, the default value is 5000. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The Volume Server produces the following message to confirm that it created +the volume: +

   Volume volume_ID created on partition partition_name of machine_name
+   
+

Examples +

The following command creates the read/write volume +user.pat on the /vicepf partition of the file +server machine fs4.abc.com. +

   % vos create -server fs4.abc.com -partition /vicepf -name user.pat
+   Volume user.pat created on partition /vicepf of fs4.abc.com
+   
+

Privilege Required +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf259.htm b/doc/html/AdminReference/auarf259.htm new file mode 100644 index 0000000..e287f22 --- /dev/null +++ b/doc/html/AdminReference/auarf259.htm @@ -0,0 +1,171 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos delentry

+ + + + +

Purpose +

Removes a volume entry from the VLDB. +

Synopsis +

vos delentry [-id <volume name or ID>⁺]
+             [-prefix <prefix of volume whose VLDB entry is to be deleted>] 
+             [-server <machine name>]  [-partition <partition name>]  
+             [-cell <cell name>]  [-noauth]  [-localauth]  [-verbose]  [-help]
+     
+vos de [-i <volume name or ID>⁺]
+       [-pr <prefix of volume whose VLDB entry is to be deleted>]  
+       [-s <machine name>]  [-pa <partition name>]  [-c <cell name>] 
+       [-n]  [-l]  [-v]  [-h]
+

Description +

The vos delentry command removes the Volume Location Database +(VLDB) entry for each specified volume. A specified volume can be any +of the three types (read/write, read-only, or backup), but the entire entry is +removed no matter which type is provided. The command has no effect on +the actual volumes on file server machines, if they exist. +

This command is useful if a volume removal operation did not update the +VLDB (perhaps because the vos zap command was used), but the system +administrator does not feel it is necessary to use the vos syncserv +and vos syncvldb commands to synchronize an entire file server +machine. +

To remove the VLDB entry for a single volume, use the -id +argument. To remove groups of volumes, combine the -prefix, +-server, and -partition arguments. The following +list describes how to remove the VLDB entry for the indicated group of +volumes: +

For every volume whose name begins with a certain character string (for +example, sys. or user.): use the +-prefix argument. +
Every volume for which the VLDB lists a site on a certain file server +machine: specify the file server name with the -server +argument. +
Every volume for which the VLDB lists a site on a partition of the same +name (for instance, on the /vicepa partition on any file server +machine): specify the partition name with the -partition +argument. +
Every volume for which the VLDB lists a site one a specific partition of a +file server machine: specify both the -server and +-partition arguments. +
Every volume whose name begins with a certain prefix and for which the +VLDB lists a site on a file server machine: combine the +-prefix and -server arguments. Combine the +-prefix argument with the -partition argument, or both +the -server and -partition arguments, to remove a more +specific group of volumes. +

Cautions +

Do not use this command to remove a volume in normal circumstances; it +does not remove a volume from the file server machine, and so is likely to +make the VLDB inconsistent with state of the volumes on server +machines. Use the vos remove command to remove both the +volume and its VLDB entry. +

Options +

-id +

Specifies the complete name or the volume ID number of each volume for +which to remove the VLDB entry. The entire entry is removed, regardless +of whether the read/write, read-only, or backup version is indicated. +Provide this argument or some combination of the -prefix, +-server, and -partition arguments. +

-prefix +

Specifies a character string of any length; the VLDB entry for a +volume whose name begins with the string is removed. Include field +separators (such as periods) if appropriate. Combine this argument with +the -server argument, -partition argument, or +both. +

-server +

Identifies a file server machine; if a volume's VLDB entry lists +a site on the machine, the entry is removed. Provide the machine's +IP address or its host name (either fully qualified or using an unambiguous +abbreviation). For details, see the introductory reference page for the +vos command suite. +

Combine this argument with the -prefix argument, the +-partition argument, or both. +

-partition +

Identifies a partition; if a volume's VLDB entry lists a site on +the partition, the entry is removed. Provide the partition's +complete name with preceding slash (for example, /vicepa) or use +one of the three acceptable abbreviated forms. For details, see the +introductory reference page for the vos command suite. +

Combine this argument with the -prefix argument, the +-server argument, or both. +

-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 vos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +

-localauth +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The following message confirms the success of the command by indicating how +many VLDB entries were removed. +

   Deleted number VLDB entries
+   
+

Examples +

The following command removes the VLDB entry for the volume +user.temp. +

   % vos delentry user.temp
+   
+

The following command removes the VLDB entry for every volume whose name +begins with the string test and for which the VLDB lists a site on +the file server machine fs3.abc.com. +

   % vos delentry -prefix test -server fs3.abc.com
+   
+

Privilege Required +

Related Information +

vos +

vos syncserv +

vos syncvldb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf260.htm b/doc/html/AdminReference/auarf260.htm new file mode 100644 index 0000000..2e3374e --- /dev/null +++ b/doc/html/AdminReference/auarf260.htm @@ -0,0 +1,193 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos dump

+ + + + + + + + + + + +

Purpose +

Converts a volume into ASCII format and writes it to a file +

Synopsis +

vos dump -id <volume name or ID>  [-time <dump from time>]  [-file <dump file>]  
+         [-server <server>]  [-partition <partition>]  [-cell <cell name>]  
+         [-noauth]  [-localauth]  [-verbose]  [-help]
+    
+vos du -i <volume name or ID>  [-t <dump from time>]  [-f <dump file>]  
+       [-s <server>]  [-p <partition>]  [-c <cell name>]  
+       [-n]  [-l]  [-v]  [-h]
+

Description +

The vos dump command converts the contents of the indicated +volume, which can be read/write, read-only or backup, into ASCII +format. The Volume Server writes the converted contents to the file +named by the -file argument, or to the standard output +stream. In the latter case, the output can be directed to a named pipe, +which enables interoperation with third-party backup utilities. +

To dump the complete contents of a volume (create a full dump), +omit the -time argument or specify the value 0 (zero) +for it. To create an incremental dump, which includes only +the files and directories in the volume that have modification timestamps +later than a certain time, specify a date and time as the value for the +-time argument. +

By default, the vos command interpreter consults the Volume +Location Database (VLDB) to learn the volume's location, so the +-server and -partition arguments are not +required. If the -id argument identifies a read-only volume +that resides at multiple sites, the command dumps the version from just one of +them (normally, the one listed first in the volume's VLDB entry as +reported by the vos examine or vos listvldb +command). To dump the read-only volume from a particular site, use the +-server and -partition arguments to specify the +site. To bypass the VLDB lookup entirely, provide a volume ID number +(rather than a volume name) as the value for the -id argument, +together with the -server and -partition +arguments. This makes it possible to dump a volume for which there is +no VLDB entry. +

During the dump operation, the volume is inaccessible both to Cache +Managers and to other volume operations. Dumping a volume does not +otherwise affect its status on the partition or its VLDB entry. +

To restore a dumped volume back into AFS, use the vos restore +command. +

Cautions +

Support for incremental dumps is provided to facilitate interoperation with +third-party backup utilities. The vos dump command does not +provide any of the administrative facilities of an actual backup system, so +the administrator must keep manual records of dump times and the relationship +between full and incremental dumps of a volume. For a volume's +contents to be consistent after restoration of incremental dumps, there must +be no gap between the time at which a prior dump of the volume was created and +the value of the -time argument to the vos dump command +that creates the incremental dump. More specifically, for a read/write +volume, the -time argument must specify the time that the prior +dump was performed, and for a read-only or backup volume it must specify the +time that the volume was last released (using the vos release +command) or cloned (using the vos backup or vos +backupsys command) prior to dumping it. The parent dump can be +either a full dump or another incremental dump. +

Options +

-id +

Specifies either the complete name or volume ID number of the read/write, +read-only, or backup volume to dump. +

-time +

Specifies whether the dump is full or incremental. Omit this +argument to create a full dump, or provide one of three acceptable +values: +

The value 0 (zero) to create a full dump. +
A date in the format +mm/dd/yyyy (month, day and +year) to create an incremental dump that includes only files and directories +with modification timestamps later than midnight (12:00 +a.m.) on the indicated date. 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 2038. The command interpreter automatically reduces later dates to +the maximum value. An example is 01/13/1999. +
A date and time in the format +"mm/dd/yyyy +hh:MM" to create an incremental +dump that includes only files and directories with modification timestamps +later than the specified date and time. The date format is the same as +for a date alone. Express the time as hours and minutes +(hh:MM) in 24-hour format (for example, +20:30 is 8:30 p.m.). Surround the +entire expression with double quotes (" ") because it contains a space. +An example is "01/13/1999 22:30". +

-file +

Specifies the pathname of the file to which to write the dump. The +file can be in AFS, but not in the volume being dumped. A partial +pathname is interpreted relative to the current working directory. If +this argument is omitted, the dump is directed to the standard output +stream. +

-server +

Specifies the file server machine on which the volume resides. +Provide the -partition argument along with this one. +

-partition +

Specifies the partition on which the volume resides. Provide the +-server argument along with this one. +

-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 vos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +

-localauth +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command writes a full dump of the volume +user.terry to the file +/afs/abc.com/common/dumps/terry.dump. +

   % vos dump -id user.terry -time 0 -file /afs/abc.com/common/dumps/terry.dump
+   
+

The following command writes an incremental dump of the volume +user.smith to the file +smith.990131.dump in the current working +directory. Only those files in the volume with modification time stamps +later than 6:00 p.m. on 31 January 1999 are included in +the dump. +

   % vos dump -id user.smith -time "01/31/1999 18:00" -file smith.990131.dump
+   
+

Privilege Required +

If the -file argument is included, the issuer must also have +permission to insert and write in the directory that houses the file. +

Related Information +

vos +

vos listvldb +

vos restore +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf261.htm b/doc/html/AdminReference/auarf261.htm new file mode 100644 index 0000000..74f03d3 --- /dev/null +++ b/doc/html/AdminReference/auarf261.htm @@ -0,0 +1,317 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos examine

+ + + + + + + + + + + +

Purpose +

Displays information from the volume header and VLDB entry for a +volume. +

Synopsis +

vos examine -id <volume name or ID>  [-extended]  [-cell <cell name>]  
+            [-noauth]  [-localauth]  [-verbose]  [-help]
+   
+vos e -i <volume name or ID>  [-e]  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+    
+vos volinfo -i <volume name or ID>  [-e]  [-c <cell name>]  
+            [-n]  [-l]  [-v]  [-h]
+   
+vos v -i <volume name or ID>  [-e]  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+   
+

Description +

The vos examine command formats and displays information from +the Volume Location Database (VLDB) entry and the volume header of the volume +specified by the -id argument. +

To display the volume header only, use the vos listvol +command. To display information from the VLDB only, use the vos +listvldb command. +

Options +

-id +: Specifies either the complete name or volume ID number of the volume, +which can be read/write, read-only, or backup. +
-extended +: Display statistics about read and write operations on files and +directories in the volume. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The first seven lines of the output show information from the volume header +and the remaining lines come from the VLDB. Each item in the following +list corresponds to a line of output derived from the volume header. +

Basic information about the specified volume (displayed on a single +line): +
- Name +
- Volume ID number + +
- Type (the flag is RW for read/write, RO for +read-only, BK for backup) +
- Size in kilobytes (1024 equals a megabyte) +
- Number of files in the volume, if the -extended flag is +provided + +
- Status on the file server machine, which is one of the following: +
  + +
  On-line +
  The volume is completely accessible to Cache Managers. + +
  Off-line +
  The volume is not accessible to Cache Managers, but does not seem to be +corrupted. This status appears while a volume is being dumped, for +example. + +
  Off-line**needs salvage** +
  The volume is not accessible to Cache Managers, because it seems to be +corrupted. Use the bos salvage or salvager +command to repair the corruption. +
  +
+
The file server machine and partition that house the volume, as determined +by the command interpreter as the command runs, rather than derived from the +VLDB or the volume header. + + + + + + + + +
The volume ID numbers associated with the various versions of the +volume: read/write (RWrite), read-only (ROnly), +backup (Backup), and ReleaseClone (RClone). One +of them matches the volume ID number that appears on the first line of the +volume's output. If the value in the RWrite, +ROnly, or Backup field is 0 (zero), there is +no volume of that type. If there is currently no ReleaseClone, the +RClone field does not appear at all. + + +
The maximum space quota allotted to the read/write copy of the volume, +expressed in kilobyte blocks in the MaxQuota field. + + +
The date and time the volume was created, in the Creation +field. If the volume has been restored with the backup +diskrestore, backup volrestore, or vos restore +command, this is the restore time. + + +
The date and time when the contents of the volume last changed, in the +Last Update field. For read-only and backup volumes, it +matches the timestamp in the Creation field. + + +
The number of times the volume has been accessed for a fetch or store +operation since the later of the two following times: +
- 12:00 a.m. on the day the command is issued +
- The last time the volume changed location +
+

When the -extended flag is included, two tables appear +next: +

The table labeled Raw Read/Write Stats contains information on +the number of reads (fetches) and writes (stores) made on the specified +volume. +
The table labeled Writes Affecting Authorship contains +information on writes made to files and directories in the specified +volume. +

   **** Volume volume_ID is busy ****
+

   **** Could not attach volume volume_ID ****
+

Following a blank line, information from the VLDB entry appears. +Each item in this list corresponds to a separate line in the output: +

The base (read/write) volume name. The read-only and backup +versions have the same name with a .readonly and +.backup extension, respectively. +
The volume ID numbers allocated to the versions of the volume that +actually exist, in fields labeled RWrite for the read/write, +ROnly for the read-only, Backup for the backup, and +RClone for the ReleaseClone. (If a field does not appear, +the corresponding version of the volume does not exist.) The appearance +of the RClone field normally indicates that a release operation did +not complete successfully; the Old release and New +release flags often also appear on one or more of the site definition +lines described just following. + + +
The number of sites that house a read/write or read-only copy of the +volume, following the string number of sites ->. + + + + + +
A line for each site that houses a read/write or read-only copy of the +volume, specifying the file server machine, partition, and type of volume +(RW for read/write or RO for read-only). If a +backup version exists, it is understood to share the read/write site. +Several flags can appear with a site definition: +
+ +
Not released +
Indicates that the vos release command has not been issued +since the vos addsite command was used to define the read-only +site. + +
Old release +
Indicates that a vos release command did not complete +successfully, leaving the previous, obsolete version of the volume at this +site. + +
New release +
Indicates that a vos release command did not complete +successfully, but that this site did receive the correct new version of the +volume. +
+
If the VLDB entry is locked, the string Volume is currently +LOCKED. +

For further discussion of the New release and Old +release flags, see the reference page for the vos release +command. +

Examples +

The following example shows output for the ABC Corporation volume called +usr with two read-only replication sites (this volume is mounted at +the /afs/abc.com/usr directory). For the sake of +illustration, the output shows the volume as locked. +

   % vos examine usr
+   usr                           536870981 RW   3459 K On-line
+        fs2.abc.com /vicepb
+        RWrite 5360870981   ROnly 536870982   Backup 536870983
+        MaxQuota      40000 K
+        Creation    Mon Jun 12 15:22:06 1989
+        Last Update Fri Jun 16 09:34:35 1989
+        5719 accesses in the past day (i.e., vnode references)
+        RWrite: 5360870981   ROnly: 536870982   Backup: 536870983
+        number of sites -> 3
+           server fs1.abc.com partition /vicepa RO Site 
+           server fs3.abc.com partition /vicepa RO Site 
+           server fs2.abc.com partition /vicepb RW Site 
+        Volume is currently LOCKED  
+   
+

The following example shows the output for the volume +user.terry using the -extended flag. The +volume has no read-only replication sites. +

   % vos examine -id user.terry -extended
+   user.terry         354287190 RW    2302 K used 119 files On-line
+       fs4.abc.com /vicepc
+       RWrite 354287190 ROnly          0 Backup 354287192
+       MaxQuota       5000 K
+       Creation    Wed Nov 25 17:38:57 1992
+       Last Update Tue Dec 15 10:46:20 1992
+       598 accesses in the past day (i.e., vnode references)
+                         Raw Read/Write Stats
+             |-------------------------------------------|
+             |    Same Network     |    Diff Network     |
+             |----------|----------|----------|----------|
+             |  Total   |   Auth   |   Total  |   Auth   |
+             |----------|----------|----------|----------|
+   Reads     |       55 |       55 |       38 |       38 |
+   Writes    |       95 |       95 |        0 |        0 |
+             |-------------------------------------------|
+                      Writes Affecting Authorship
+             |-------------------------------------------|
+             |   File Authorship   | Directory Authorship|
+             |----------|----------|----------|----------|
+             |   Same   |   Diff   |    Same  |   Diff   |
+             |----------|----------|----------|----------|
+   0-60 sec  |       38 |        0 |       21 |        1 |
+   1-10 min  |        2 |        0 |        7 |        0 |
+   10min-1hr |        0 |        0 |        1 |        0 |
+   1hr-1day  |        1 |        0 |        5 |        1 |
+   1day-1wk  |        0 |        0 |        0 |        0 |
+   > 1wk     |        0 |        0 |        0 |        0 |
+             |-------------------------------------------|
+       RWrite: 354287190    Backup: 354287192
+       number of sites -> 1
+          server fs4.abc.com partition /vicepc RW Site
+   
+

Privilege Required +

None +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf262.htm b/doc/html/AdminReference/auarf262.htm new file mode 100644 index 0000000..b131a68 --- /dev/null +++ b/doc/html/AdminReference/auarf262.htm @@ -0,0 +1,85 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos help

+ + + +

Purpose +

Displays the syntax of specified vos commands or functional +descriptions for all vos commands +

Synopsis +

vos help [-topic <help string>⁺]  [-help]
+    
+vos h [-t <help string>⁺]  [-h]
+

Description +

The vos help command displays the complete online help entry +(short description and syntax statement) for each command operation code +specified by the -topic argument. If the -topic +argument is omitted, the output includes the first line (name and short +description) of the online help entry for every vos command. +

To list every vos command whose name or short description +includes a specified keyword, use the vos apropos command. +

Options +

-topic +: Identifies each command for which to display the complete online help +entry. Omit the vos part of the command name, providing only +the operation code (for example, specify create, not vos +create). If this argument is omitted, the output briefly +describes every vos command. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The online help entry for each vos command consists of the +following two or three lines: +

The first line names the command and briefly describes its +function. +
The second line lists aliases for the command, if any. +
The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in this +document. +

Examples +

The following command displays the online help entry for the vos +create command: +

   % vos help create
+   vos create: create a new volume 
+   Usage: vos create -server <machine name> -partition <partition name> 
+   -name <volume name> [-cell <cell name>] [-noauth] [-localauth] 
+   [-verbose] [-help]
+   
+

Privilege Required +

None +

Related Information +

vos +

vos apropos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf263.htm b/doc/html/AdminReference/auarf263.htm new file mode 100644 index 0000000..06bdbc0 --- /dev/null +++ b/doc/html/AdminReference/auarf263.htm @@ -0,0 +1,103 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos listaddrs

+ + + + + +

Purpose +

Displays all VLDB server entries +

Synopsis +

vos listaddrs [-cell <cell name>]  [-noauth]
+              [-localauth]  [-verbose]  [-help]
+    
+vos lista [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos listaddrs command displays all of the server entries +from the Volume Location Database (VLDB). An entry is created as the +File Server initializes and registers the contents of its +/usr/afs/local/sysid file in the VLDB. +

Options +

-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output displays all server entries from the VLDB, each on its own +line. If a file server machine is multihomed, all of its registered +addresses appear on the line. The first one is the one reported as a +volume's site in the output from the vos examine and vos +listvldb commands. +

The VLDB records IP addresses, and the command interpreter has the local +name service (either a process like the Domain Name Service or a local host +table) translate them to hostnames before displaying them. If an IP +address appears in the output, it is not possible to translate it. +

The existence of an entry does not necessarily indicate that the machine +that is still an active file server machine. To remove obsolete server +entries, use the vos changeaddr command with the -remove +argument. +

Examples +

The following command displays the VLDB server entries in the ABC +Corporation cell: +

   % vos listaddrs 
+   sv5.abc.com
+   sv1.abc.com
+   sv2.abc.com  afs2.abc.com
+   sv6.abc.com
+   
+

Privilege Required +

None +

Related Information +

vos +

vos changeaddr +

vos listvldb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf264.htm b/doc/html/AdminReference/auarf264.htm new file mode 100644 index 0000000..47dd5e0 --- /dev/null +++ b/doc/html/AdminReference/auarf264.htm @@ -0,0 +1,98 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos listpart

+ + + + + +

Purpose +

Displays all AFS partitions on a file server machine +

Synopsis +

vos listpart -server <machine name>  [-cell <cell name>]  [-noauth]
+             [-localauth]  [-verbose]  [-help]
+    
+vos listp -s <machine name>  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos listpart command displays all of the valid AFS +partitions on the indicated file server machine, without consulting the Volume +Location Database (VLDB). The vos partinfo command reports +the size of a partition and the available space on that partition. +

Options +

-server +: Identifies the file server machine for which to list the +partitions. Provide the machine's IP address or its host name +(either fully qualified or using an unambiguous abbreviation). For +details, see the introductory reference page for the vos command +suite. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The output consists of a list of partition names of the form +/vicepxx, following the header: +

   The partitions on the server are:
+   
+

The last line of the output reports the total number of partitions. +

Examples +

The following command displays the partitions on +fs1.abc.com: +

   % vos listpart fs1.abc.com
+   The partitions on the server are:
+       /vicepa     /vicepb     /vicepc     /vicepd
+   Total:  4
+   
+

Privilege Required +

None +

Related Information +

vos +

vos partinfo +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf265.htm b/doc/html/AdminReference/auarf265.htm new file mode 100644 index 0000000..b495b4d --- /dev/null +++ b/doc/html/AdminReference/auarf265.htm @@ -0,0 +1,231 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos listvldb

+ + + + + + + + + + + +

Purpose +

Displays a volume's VLDB entry +

Synopsis +

vos listvldb [-name <volume name or ID>]  [-server <machine name>]  
+             [-partition <partition name>]  [-locked]  [-quiet]  [-nosort]  
+             [-cell <cell name>]  [-noauth]  [-localauth]  [-verbose]  [-help]
+    
+vos listvl [-na <volume name or ID>]  [-s <machine name>]
+           [-p <partition name>]  [-lock]  [-q]  [-nos]  [-c <cell name>]  
+           [-noa]  [-loca]  [-v]  [-h]
+

Description +

The vos listvldb command formats and displays information from +the Volume Location Database (VLDB) entry for each volume specified. +The output depends on the combination of options supplied on the command +line. Combine options as indicated to display the desired type of VLDB +entries: +

Every entry in the VLDB: provide no options +
Every VLDB entry that mentions a certain file server machine as the site +for a volume: specify the machine's name as the -server +argument +
Every VLDB entry that mentions a certain partition on any file server +machine as the site for a volume: specify the partition name as the +-partition argument +
Every VLDB entry that mentions a certain partition on a certain file +server machine as the site for a volume: combine the -server +and -partition arguments +
A single VLDB entry: specify a volume name or ID number with the +-name argument +
The VLDB entry only for the volumes with locked VLDB entries found at a +certain site: combine the -locked flag with any of arguments +that define sites +

Options +

-name +

Specifies either the complete name or volume ID number of a volume of any +of the three types. +

-server +

Identifies the file server machine listed as a site in each VLDB entry to +display. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +

This argument can be combined with the -partition argument, the +-locked flag, or both. +

-partition +

Identifies the partition (on the file server machine specified by the +-server argument) listed as a site in each VLDB entry to +display. Provide the partition's complete name with preceding +slash (for example, /vicepa) or use one of the three acceptable +abbreviated forms. For details, see the introductory reference page for +the vos command suite. +

This argument can be combined with the -server argument, the +-locked flag, or both. +

-locked +

Displays only locked VLDB entries. This flag can be combined with +the -server argument, the -partition argument, or +both. +

-quiet +

Suppresses the lines that summarize the number of volumes listed and their +status, which otherwise appear at the beginning and end of the output when the +output includes more than one volume. +

-nosort +

Suppresses the default sorting of volume entries alphabetically by volume +name. +

-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 vos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +

-localauth +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

If the output includes more than one VLDB entry, by default the first line +reports which file server machine, partition, or both, houses the +volumes. The final line of output reports the total number of entries +displayed. Including the -quiet flag suppresses these +lines. +

By default, volumes are sorted alphabetically by volume name. +Including the -nosort flag skips the sorting step, which can speed +up the production of output if there are a large number of entries. +

The VLDB entry for each volume includes the following information: +

The base (read/write) volume name. The read-only and backup +versions have the same name with a .readonly and +.backup extension, respectively. +
The volume ID numbers allocated to the versions of the volume that +actually exist, in fields labeled RWrite for the read/write, +ROnly for the read-only, Backup for the backup, and +RClone for the ReleaseClone. (If a field does not appear, +the corresponding version of the volume does not exist.) The appearance +of the RClone field normally indicates that a release operation did +not complete successfully; the Old release and New +release flags often also appear on one or more of the site definition +lines described just following. + + +
The number of sites that house a read/write or read-only copy of the +volume, following the string number of sites ->. + + + + + +
A line for each site that houses a read/write or read-only copy of the +volume, specifying the file server machine, partition, and type of volume +(RW for read/write or RO for read-only). If a +backup version exists, it is understood to share the read/write site. +Several flags can appear with a site definition: +
+ +
Not released +
Indicates that the vos release command has not been issued +since the vos addsite command was used to define the read-only +site. + +
Old release +
Indicates that a vos release command did not complete +successfully, leaving the previous, obsolete version of the volume at this +site. + +
New release +
Indicates that a vos release command did not complete +successfully, but that this site did receive the correct new version of the +volume. +
+
If the VLDB entry is locked, the string Volume is currently +LOCKED. +

For further discussion of the New release and Old +release flags, see the reference page for the vos release +command. +

Examples +

The following command displays VLDB information for the ABC Corporation +volume called usr, which has two read-only replication sites: +

   % vos listvldb -name usr
+   usr 
+    RWrite: 5360870981   ROnly: 536870982   Backup: 536870983
+    number of sites -> 3
+       server fs1.abc.com partition /vicepa RO Site 
+       server fs3.abc.com partition /vicepa RO Site 
+       server fs2.abc.com partition /vicepb RW Site 
+   
+

The following example shows entries for two of the volumes that reside on +the file server machine fs4.abc.com. The first +VLDB entry is currently locked. There are 508 entries that mention the +machine as a volume site. +

   % vos listvldb -server fs4.abc.com
+   VLDB entries for server fs4.abc.com
+       .       .           .        .
+       .       .           .        .
+   user.smith 
+    RWrite: 278541326   ROnly: 278541327   Backup: 278542328
+    number of sites -> 1
+      server fs4.abc.com partition /vicepg RW Site 
+    Volume is currently LOCKED
+      user.terry
+    RWrite 354287190   ROnly 354287191   Backup 354287192
+    number of sites -> 1
+      server fs4.abc.com partition /vicepc RW Site 
+      .       .           .        .
+      .       .           .        .
+   Total entries: 508
+   
+

Privilege Required +

None +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf266.htm b/doc/html/AdminReference/auarf266.htm new file mode 100644 index 0000000..aae8da4 --- /dev/null +++ b/doc/html/AdminReference/auarf266.htm @@ -0,0 +1,308 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos listvol

+ + + + + + + + + + + +

Purpose +

Displays information from a volume header +

Synopsis +

vos listvol -server <machine name>  [-partition <partition name>]
+            [-fast]  [-long]  [-quiet]  [-extended]  [-cell <cell name>]  
+            [-noauth]  [-localauth]  [-verbose]  [-help]
+    
+vos listvo -s <machine name>  [-p <partition name>]  [-f]  [-lon]  
+           [-q]  [-e]  [-c <cell name>]  [-n]  [-loc]  [-v]  [-h]
+

Description +

The vos listvol command formats and displays the following +information from the volume header of each specified volume: volume +name, volume ID, volume type, size, and status at the server. The +actual information displayed depends on the combination of arguments supplied +when the command is issued. To display volume header information for +various numbers of volumes, combine the command's arguments as +indicated: +

For every volume on a file server machine, specify the machine's name +with the -server argument. +
For every volume at a particular site, combine the -server +argument with the -partition argument. +

To display the Volume Location Database (VLDB) entry for one or more +volumes, use the vos listvldb command. To display both the +VLDB entry and the volume header for a single volume, use the vos +examine command. +

Options +

-server +

Identifies the file server machine that houses volumes for which to +display the header. Provide the machine's IP address or its host +name (either fully qualified or using an unambiguous abbreviation). For +details, see the introductory reference page for the vos command +suite. +

This argument can be combined with the -partition argument, as +well as the -fast, -long, or -extended +flag. +

-partition +

Identifies the partition (on the file server machine specified by the +-server argument) that houses volumes for which to display the +header. Provide the partition's complete name with preceding slash +(for example, /vicepa) or use one of the three acceptable +abbreviated forms. For details, see the introductory reference page for +the vos command suite. +

-fast +

Displays only the volume ID numbers of volumes stored at the site +specified by the -server, and optionally -partition, +argument. Do not combine this flag with the -extended +flag. +

-long +

Displays more detailed information about each volume stored at the site +specified by the -server, and optionally -partition, +argument. The information includes the volume IDs of all three volume +types associated with the volume, and the read/write volume's quota, +creation date and update date. +

-quiet +

Suppresses the lines that summarize the number of volumes listed and their +status, which otherwise appear at the beginning and end of the output when the +output includes more than one volume. +

-extended +

Displays extensive statistics about access patterns for each volume stored +at the site specified by the -server, and optionally +-partition, argument. The statistics include the number of +reads and writes to files in the volume, and how recently files and +directories have been updated by their owners or other users. Do not +combine this flag with the -fast flag. +

-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 vos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +

-localauth +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The output is ordered alphabetically by volume name and by default provides +the following information on a single line for each volume: +

Name +
Volume ID number + +
Type (the flag is RW for read/write, RO for +read-only, BK for backup) +
Size in kilobytes (1024 equals a megabyte) +
Number of files in the volume, if the -extended flag is +provided + +
Status on the file server machine, which is one of the following: +
+ +
On-line +
The volume is completely accessible to Cache Managers. + +
Off-line +
The volume is not accessible to Cache Managers, but does not seem to be +corrupted. This status appears while a volume is being dumped, for +example. + +
Off-line**needs salvage** +
The volume is not accessible to Cache Managers, because it seems to be +corrupted. Use the bos salvage or salvager +command to repair the corruption. +
+

   **** Volume volume_ID is busy ****
+

   **** Could not attach volume volume_ID ****
+

If the -fast flag is added, the output displays only the volume +ID number of each volume, arranged in increasing numerical order. The +final line (which summarizes the number of online, offline, and busy volumes) +is omitted. +

If the -long flag is included, the output for each volume +includes all of the information in the default listing plus the +following. Each item in this list corresponds to a separate line of +output: +

The file server machine and partition that house the volume, as determined +by the command interpreter as the command runs, rather than derived from the +VLDB or the volume header. + + + + + + + + +
The volume ID numbers associated with the various versions of the +volume: read/write (RWrite), read-only (ROnly), +backup (Backup), and ReleaseClone (RClone). One +of them matches the volume ID number that appears on the first line of the +volume's output. If the value in the RWrite, +ROnly, or Backup field is 0 (zero), there is +no volume of that type. If there is currently no ReleaseClone, the +RClone field does not appear at all. + + +
The maximum space quota allotted to the read/write copy of the volume, +expressed in kilobyte blocks in the MaxQuota field. + + +
The date and time the volume was created, in the Creation +field. If the volume has been restored with the backup +diskrestore, backup volrestore, or vos restore +command, this is the restore time. + + +
The date and time when the contents of the volume last changed, in the +Last Update field. For read-only and backup volumes, it +matches the timestamp in the Creation field. + + +
The number of times the volume has been accessed for a fetch or store +operation since the later of the two following times: +
- 12:00 a.m. on the day the command is issued +
- The last time the volume changed location +
+

If the -extended flag is included, the output for each volume +includes all of the information reported with the -long flag, plus +two tables of statistics: +

The table labeled Raw Read/Write Stats table summarizes the +number of times the volume has been accessed for reading or writing. +
The table labeled Writes Affecting Authorship table contains +information on writes made to files and directories in the specified +volume. +

Examples +

The following example shows the output for the /vicepb partition +on the file server machine fs2.abc.com when no flags +are provided: +

   % vos listvol -server fs2.abc.com -partition b
+   Total number of volumes on server fs2.abc.com   \
+                                       partition /vicepb : 66
+   sys                  1969534847 RW       1582 K On-line
+   sys.backup           1969535105 BK       1582 K On-line
+         .                   .     .         .   .    .
+         .                   .     .         .   .    .
+   user.pat             1969534536 RW      17518 K On-line
+   user.pat.backup      1969534538 BK      17537 K On-line
+   Total volumes onLine 66 ; Total volumes offLine 0 ;  Total busy 0
+   
+

The following example shows the output when the -fast flag is +added: +

   % vos listvol -server fs2.abc.com -partition b -fast
+   Total number of volumes on server fs2.abc.com   \
+                                       partition /vicepb : 66
+    1969516782
+    1969516784
+        .
+        .
+    1969535796
+    
+

The following example shows two volumes from the output that appears when +the -long flag is added: +

   % vos listvol -server fs2.abc.com -partition b -long
+   Total number of volumes on server fs2.abc.com \
+                                       partition /vicepb: 66
+         .                   .      .         .   .    .
+         .                   .      .         .   .    .
+   user.pat             1969534536 RW      17518 K On-line
+        fs2.abc.com /vicepb
+        RWrite 1969534536 ROnly 0        Backup 1969534538 
+        MaxQuota      20000 K
+        Creation    Mon Jun 12 09:02:25 1989
+        Last Update Thu May 20 17:39:34 1999
+        1573 accesses in the past day (i.e., vnode references)
+   user.pat.backup      1969534538 BK      17537 K On-line
+        fs2.abc.com /vicepb
+        RWrite 1969534536 ROnly 0        Backup 1969534538 
+        MaxQuota      20000 K
+        Creation    Tue Jun 13 04:37:59 1989
+        Last Update Wed May 19 06:37:59 1999
+        0 accesses in the past day (i.e., vnode references)
+          .                   .      .         .   .    .
+          .                   .      .         .   .    .
+   Total volumes onLine 66 ; Total volumes offLine 0 ; \
+                                                Total busy 0
+   
+

Privilege Required +

None +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf267.htm b/doc/html/AdminReference/auarf267.htm new file mode 100644 index 0000000..ea7d5c7 --- /dev/null +++ b/doc/html/AdminReference/auarf267.htm @@ -0,0 +1,99 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos lock

+ + + + + +

Purpose +

Locks a VLDB volume entry +

Synopsis +

vos lock -id <volume name or ID>  [-cell <cell name>]  [-noauth] 
+         [-localauth]  [-verbose]  [-help]
+   
+vos lo -i <volume name or ID>  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos lock command locks the Volume Location Database (VLDB) +entry for the indicated volume, blocking any operation that requires a write +to that entry. The lock applies to all of the volume versions +associated with the entry, not just the one specified with the -id +argument. +

To unlock a single VLDB entry, use the vos unlock +command. To unlock several entries, or all locked entries in the VLDB, +use the vos unlockvldb command. +

Cautions +

Do not use this command in normal circumstances. It is useful for +guaranteeing that the volume stays unchanged when there is reason to believe +that volume operations cannot properly lock VLDB volume entries as they +normally do to synchronize with one another. +

Options +

-id +: Specifies either the complete name or volume ID number of a volume of the +any of the three types. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command locks the VLDB entry for +user.terry. +

   % vos lock user.terry
+    
+

Privilege Required +

Related Information +

vos +

vos unlock +

vos unlockvldb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf268.htm b/doc/html/AdminReference/auarf268.htm new file mode 100644 index 0000000..66e424a --- /dev/null +++ b/doc/html/AdminReference/auarf268.htm @@ -0,0 +1,166 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos move

+ + + + + + + + + +

Purpose +

Moves a read/write volume to another site +

Synopsis +

vos move -id <volume name or ID>  -fromserver <machine name on source> 
+         -frompartition <partition name on source> 
+         -toserver <machine name on destination>  
+         -topartition <partition name on destination> 
+         [-cell <cell name>]  [-noauth]  [-localauth]  [-verbose]  [-help] 
+    
+vos m -i <volume name or ID>  -froms <machine name on source> 
+      -fromp <partition name on source>  -tos <machine name on destination> 
+      -top <partition name on destination>  [-c <cell name>]  
+      [-n]  [-l]  [-v]  [-h]
+

Description +

The vos move command moves the indicated read/write volume from +its current site (specified with the -fromserver and +-frompartition arguments) to the destination site (specified with +the -toserver and -topartition arguments). This +command automatically removes the backup copy from the current site, if it +exists. To create a new backup volume at the destination site, use the +vos backup command. +

This command works on read/write volumes only. To move a read-only +volume, use the vos addsite and vos release commands to +define a new read-only site and release the volume contents to it, and then +use the vos remove command to remove the previous read-only +volume's definition from the Volume Location Database (VLDB) and data +from the partition. To move a backup volume, use this command to move +its read/write source and then issue the vos backup command. +

Before executing this command, the vos command interpreter +initiates a check that the destination partition contains enough space to +house the volume being moved. If there is not enough space, the move +operation is not attempted and the following message appears: +

   vos: no space on target partition dest_part to move volume volume
+   
+

Cautions +

Unless there is a compelling reason, do not interrupt a vos move +command in progress. Interrupting a move can result in one or more of +the following inconsistent states: +

There are two versions of the volume, one at the source site and one at +the destination site. (If this happens, retain the version identified +by the VLDB and use the vos zap command to remove the other +version.) +
The backup version of the volume is stranded at the old site. (If +this happens, use the vos zap command to remove it.) +
The volume is off-line. (If this happens, run the bos +salvage command to bring it back on line.) +

If the <Ctrl-c> interrupt signal is pressed while a vos +move operation is executing, the following message warns of the +consequences and requests confirmation of the kill signal: +

   SIGINT handler: vos move operation in progress
+   WARNING: may leave AFS storage and metadata in indeterminate state
+   enter second control-c to exit
+   
+

To confirm termination of the operation, press <Ctrl-c> a +second time; press any other key to continue the operation. +

Options +

-id +: Specifies either the complete name or volume ID number of a read/write +volume. +
-fromserver +: Identifies the file server machine where the volume currently +resides. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +
-frompartition +: Names the partition where the volume currently resides. Provide the +full partition name (for, example, /vicepa) or one of the +abbreviated forms described on the introductory vos reference +page. +
-toserver +: Identifies the file server machine to which to move the volume. +Provide the machine's IP address or its host name (either fully qualified +or using an unambiguous abbreviation). For details, see the +introductory reference page for the vos command suite. +
-topartition +: Names the partition to which to move the volume. Provide the full +partition name (for, example, /vicepa) or one of the abbreviated +forms described on the introductory vos 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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example moves the volume user.smith from +the /vicepb partition on the file server machine +fs3.abc.com to the /vicepg partition on +the file server machine fs7.abc.com. +

   % vos move -id user.smith -fromserver fs3.abc.com -frompartition b  \
+              -toserver fs7.abc.com -topartition g
+   
+

Privilege Required +

The issuer must be listed in the /usr/afs/etc/UserList file on +the machines specified with the -toserver and +-fromserver arguments and on each database server machine. +If the -localauth flag is included, the issuer must instead be +logged on to a server machine as the local superuser root. +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf269.htm b/doc/html/AdminReference/auarf269.htm new file mode 100644 index 0000000..c2a0201 --- /dev/null +++ b/doc/html/AdminReference/auarf269.htm @@ -0,0 +1,115 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos partinfo

+ + + + + + + +

Purpose +

Reports the available and total space on a partition +

Synopsis +

vos partinfo -server <machine name>  [-partition <partition name>] 
+             [-cell <cell name>]  [-noauth]  [-localauth]  [-verbose]  [-help]
+   
+vos p -s <machine name>  [-p <partition name>]  [-c <cell name>]  
+      [-n]  [-l]  [-v]  [-h]
+

Description +

The vos partinfo command reports the amount of space available +and total size on either all of the partitions on the indicated +file server machine (if the -partition argument is omitted) +or the specified partition on that file server machine. The +Volume Location Database (VLDB) is not consulted. +

Options +

-server +: Identifies the file server machine for which to display partition +information. Provide the machine's IP address or its host name +(either fully qualified or using an unambiguous abbreviation). For +details, see the introductory reference page for the vos command +suite. +
-partition +: Identifies which partition on the file server machine specified by the +-server argument for which to display information. Provide +the partition's complete name with preceding slash (for example, +/vicepa) or use one of the three acceptable abbreviated +forms. For details, see the introductory reference page for the +vos command suite. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Cautions +

Output +

The output reports the amount of space available and total space for each +specified partition. +

Examples +

The following command displays all partitions on the file server machine +fs2.abc.com. +

   % vos partinfo fs2.abc.com
+   Free space on partition /vicepa: 27301 K blocks out of total 549197
+   Free space on partition /vicepb: 13646 K blocks out of total 69194
+   Free space on partition /vicepc: 31798 K blocks out of total 320315
+   Free space on partition /vicepd: 33302 K blocks out of total 494954
+   
+

Privilege Required +

None +

Related Information +

vos +

vos listpart +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf270.htm b/doc/html/AdminReference/auarf270.htm new file mode 100644 index 0000000..9dafa61 --- /dev/null +++ b/doc/html/AdminReference/auarf270.htm @@ -0,0 +1,187 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos release

+ + + + + + + + + + + + + + + + + + + + + + + +

Purpose +

Updates the contents of read-only volumes to match their read/write source +volume +

Synopsis +

vos release -id <volume name or ID>  [-f]  [-cell <cell name>] 
+            [-noauth]  [-localauth]  [-verbose]  [-help]
+    
+vos rel -i <volume name or ID>  [-f]  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos release command copies the contents of the indicated +read/write source volume to each read-only site defined in the source +volume's Volume Location Database (VLDB) entry. (Use the vos +addsite command to define sites as necessary before issuing this +command). Each read-only copy has the same name as read/write source +with the addition of a .readonly extension. +

For users to have a consistent view of the file system, the release of the +new volume version must be atomic: either all read-only sites receive +the new version, or all sites keep the version they currently have. The +vos release command is designed to ensure that all copies of the +volume's read-only version match both the read/write source and each +other. In cases where problems such as machine or server process +outages prevent successful completion of the release operation, AFS uses two +mechanisms to alert the administrator. +

Before the operation begins, the VL Server sets the New release +flag on the read/write site definition in the VLDB entry and the Old +release flag on read-only site definitions (unless the read-only site +has been defined since the last release operation and has no actual volume, in +which case its site flag remains Not released). +
If necessary, the Volume Server creates a temporary copy (a +clone) of the read/write source called the ReleaseClone (see the +following discussion of when the Volume Server does or does not create a new +ReleaseClone.) It assigns the ReleaseClone its own volume ID number, +which the VL Server records in the RClone field of the source +volume's VLDB entry. +
The Volume Server distributes a copy of the ReleaseClone to each read-only +site defined in the VLDB entry. As the site successfully receives the +new clone, the VL Server sets the site's flag in the VLDB entry to +New release. +
When all the read-only copies are successfully released, the VL Server +clears all the New release site flags. The ReleaseClone is +no longer needed, so the Volume Server deletes it and the VL Server erases its +ID from the VLDB entry. +

By default, the Volume Server determines automatically whether or not it +needs to create a new ReleaseClone: +

If there are no flags (New release, Old release, or +Not released) on site definitions in the VLDB entry, the previous +vos release command completed successfully and all read-only sites +currently have the same volume. The Volume Server infers that the +current vos release command was issued because the read/write +volume has changed. The Volume Server creates a new ReleaseClone and +distributes it to all of the read-only sites. +
If any site definition in the VLDB entry is marked with a flag, either the +previous release operation did not complete successfully or a new read-only +site was defined since the last release. The Volume Server does not +create a new ReleaseClone, instead distributing the existing ReleaseClone to +sites marked with the Old release or Not released +flag. As previously noted, the VL Server marks each VLDB site +definition with the New release flag as the site receives the +ReleaseClone, and clears all flags after all sites successfully receive +it. +

Options +

-id +: Specifies either the complete name or volume ID number of a read/write +volume. +
-f +: Creates a new ReleaseClone and distributes it all read-only sites +regardless of whether or not any site definitions in the VLDB entry are marked +with a flag. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command clones the read/write volume usr and +releases it to the read-only sites defined in its VLDB entry. +

   % vos release usr
+   
+

Privilege Required +

Related Information +

vos +

vos addsite +

vos listvldb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf271.htm b/doc/html/AdminReference/auarf271.htm new file mode 100644 index 0000000..e5915dc --- /dev/null +++ b/doc/html/AdminReference/auarf271.htm @@ -0,0 +1,169 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos remove

+ + + + + + + + +

Purpose +

Removes a volume from a site +

Synopsis +

vos remove [-server <machine name>]  [-partition <partition name>]
+           -id <volume name or ID>  [-cell <cell name>]
+           [-noauth]  [-localauth]  [-verbose]  [-help]
+    
+vos remo [-s <machine name>]  [-p <partition name>]  -i <volume name or ID> 
+         [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos remove command removes the indicated volume from the +partition on which it resides. The Volume Location Database (VLDB) +record is altered appropriately, as described in the following +paragraphs. Use this command to remove any of the three types of +volumes; the effect depends on the type. +

If the -id argument names the read/write volume (that is, +specifies the volume's base name), both it and the associated backup +volume are removed from the partition that houses them. The +-server and -partition arguments are optional, because +there can be only one read/write site. When the volume is removed, the +site information is also removed from the VLDB entry. The read/write +and backup volume ID numbers no longer appear in the output from the vos +listvldb or vos examine commands, but they are preserved +internally. Read-only sites, if any, are not affected, but cannot be +changed unless a read/write site is again defined. The site count +reported by the vos examine and vos listvldb commands as +number of sites decrements by one. The entire VLDB entry is +removed if there are no read-only sites. +
If the -id argument names a read-only volume, it is removed +from the partition that houses it, and the corresponding site information is +removed from the VLDB entry. The site count reported by the vos +examine and vos listvldb commands as number of +sites decrements by one for each volume you remove. If there is +more than one read-only site, the -server argument (and optionally +-partition argument) must be used to specify the site from which to +remove the volume. If there is only one read-only site, the +-id argument is sufficient; if there is also no read/write +volume in this case, the entire VLDB entry is removed. +
If the -id argument names a backup volume, it is removed from +the partition that houses it. The -server and +-partition arguments are optional, because there can be only one +backup site. The backup volume ID number no longer appears in the +output from the vos listvldb command or in the corresponding +portion of the output from the vos examine command, but is +preserved internally. +

This command is the most appropriate one for removing volumes in almost all +cases. Other commands that remove only volumes or only VLDB entries +(such as the vos delentry, vos remsite and vos +zap commands) by definition can put the volumes and VLDB out of +sync. Use them only in the special circumstances mentioned on their +reference pages. Like the vos delentry command, this command +can remove a VLDB entry when no corresponding volumes exist on the file server +machine. Like the vos zap command, this command can remove a +volume that does not have a VLDB entry, as long as the volume is online, +-server and -partition arguments are provided, and the +-id argument specifies the volume's ID number. +

Options +

-server +

Identifies the file server machine that houses the volume to +remove. It is necessary only when the -id argument names a +read-only volume that exists at multiple sites. Provide the +machine's IP address or its host name (either fully qualified or using an +unambiguous abbreviation). For details, see the introductory reference +page for the vos command suite. +

-partition +

Identifies the partition (on the file server machine specified by the +-server argument) that houses the volume to remove. Provide +the partition's complete name with preceding slash (for example, +/vicepa) or use one of the three acceptable abbreviated +forms. For details, see the introductory reference page for the +vos command suite. +

Including this argument is necessary only when the -id argument +names a read-only volume that exists at multiple sites. Provide the +-server argument along with this one. +

-id +

Identifies the volume to remove, either by its complete name or volume ID +number. If identifying a read-only or backup volume by name, include +the appropriate extension (.readonly or +.backup). +

Note:

If the -server and -partition arguments are omitted, +the -id switch must be provided. +

-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 vos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +

-localauth +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example removes the read/write volume +user.terry and its backup version, if any. +

   % vos remove  -id user.terry
+   
+

The following example removes the read-only volume +root.afs.readonly from one of its sites, the +/vicepa partition on the file server machine +fs1.abc.com. +

   % vos remove fs1.abc.com  a  root.afs.readonly
+   
+

Privilege Required +

Related Information +

vos +

vos delentry +

vos remsite +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf272.htm b/doc/html/AdminReference/auarf272.htm new file mode 100644 index 0000000..e5efa83 --- /dev/null +++ b/doc/html/AdminReference/auarf272.htm @@ -0,0 +1,120 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos remsite

+ + + + + + +

Purpose +

Removes a read-only site definition from a VLDB entry +

Synopsis +

vos remsite -server <machine name>  -partition <partition name> 
+            -id <volume name or ID>  [-cell <cell name>]  [-noauth] 
+            [-localauth]  [-verbose]  [-help]
+    
+vos rems -s <machine name>  -p <partition name>  -i <volume name or ID>  
+         [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos remsite command removes the read-only replication site +specified by the -machine and -partition arguments from +the Volume Location Database (VLDB) entry for the indicated volume, which is +read/write. +

This command is useful for removing read-only sites that were mistakenly +created with the vos addsite command, before the vos +release command actually releases them. If a read-only copy +already exists at the site, it is not affected. However, if this +read-only site was the last site housing any version of the volume, then the +entire VLDB entry is removed, even if a copy of the read-only version still +actually exists at the site. The VL Server does not correct the +discrepancy until the vos syncserv and vos syncvldb +commands are run. +

Cautions +

Do not use this command as the standard way to remove a read-only volume, +because it can create a discrepancy between the VLDB and the volumes on file +server machines. Use the vos remove command instead. +

Options +

-server +: Specifies the file server machine portion of the site definition to +remove. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +
-partition +: Specifies the partition name portion of the site definition to +remove. Provide the partition's complete name with preceding slash +(for example, /vicepa) or use one of the three acceptable +abbreviated forms. For details, see the introductory reference page for +the vos command suite. +
-id +: Specifies either the complete name or volume ID number of the read/write +volume to remove. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command removes the mistakenly defined read-only site +/viceph on the file server machine +fs5.abc.com from the VLDB entry for the volume +root.cell. +

   % vos remsite -server fs5.abc.com -partition h -id root.cell
+   
+

Privilege Required +

Related Information +

vos +

vos delentry +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf273.htm b/doc/html/AdminReference/auarf273.htm new file mode 100644 index 0000000..017a755 --- /dev/null +++ b/doc/html/AdminReference/auarf273.htm @@ -0,0 +1,109 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos rename

+ + + + + + + + + + +

Purpose +

Renames a volume +

Synopsis +

vos rename -oldname <old volume name>  -newname <new volume name> 
+           [-cell <cell name>]  [-noauth]  [-localauth]  [-verbose]  [-help]
+    
+vos ren -o <old volume name>  -ne <new volume name>  [-c <cell name>]
+        [-no]  [-l]  [-v]  [-h]
+

Description +

The vos rename command changes the name of the read/write volume +specified with the -oldname argument to the name specified with the +-newname argument. The names of the read/write's +read-only copies and backup copy, if any, change automatically to +match. +

After issuing this command, remember to correct any mount points that refer +to the old volume name, by removing the old mount point with the fs +rmmount command and creating a new one with the fs mkmount +command. +

Options +

-oldname +: Is the current name of the read/write volume. +
-newname +: Is the desired new name for the volume. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

The vos rename command produces no output if the command +succeeds. +

If the volume named by the -oldname argument does not exist, the +following message appears: +

   vos: Could not find entry for volume old volume name.
+   
+

Examples +

The following example changes the mistaken volume name +sun4x_56.afsws to the correct alternative +sun4x_56.usr.afsws. +

   % vos rename -oldname sun4x_56.afsws -newname sun4x_56.usr.afsws
+   
+

Privilege Required +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf274.htm b/doc/html/AdminReference/auarf274.htm new file mode 100644 index 0000000..d58ae6e --- /dev/null +++ b/doc/html/AdminReference/auarf274.htm @@ -0,0 +1,194 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos restore

+ + + + +

Purpose +

Converts an ASCII file into proper volume format and writes it to the file +system +

Synopsis +

vos restore -server <machine name>  -partition <partition name>  
+            -name <name of volume to be restored>  [-file <dump file>]  
+            [-id <volume ID>]  [-overwrite <abort | full | incremental>]  
+            [-cell <cell name>]  [-noauth]  [-localauth]  [-verbose]  
+            [-help]
+   
+vos res -s <machine name>  -p <partition name>  
+        -na <name of volume to be restored>  [-f <dump file>]  
+        [-i <volume ID>]  [-o <a | f | inc>]  [-c <cell name>]  
+        [-no]  [-l]  [-v]  [-h]
+

Description +

The vos restore command converts a volume dump file previously +created with the vos dump command from ASCII into the volume format +appropriate for the machine type indicated by the -server argument, +and restores it as a read/write volume to the partition named by the +-partition argument on that machine. The Volume Server +assigns the volume name indicated with the -name argument, and +resets the volume's creation timestamp to the time at which the restore +operation begins (the creation timestamp is stored in the volume header and +reported in the Creation field in the output from the vos +examine and vos listvol commands.) +

Use the -file argument to name the dump file, or omit the +argument to provide the file via the standard input stream, presumably through +a pipe. The pipe can be named, which enables interoperation with +third-party backup utilities. +

As described in the following list, the command can create a completely new +volume or overwrite an existing volume. In all cases, the full dump of +the volume must be restored before any incremental dumps. If there are +multiple incremental dump files, they must be restored in the order they were +created. +

To create a new read/write volume, use the -name argument to +specify a volume name that does not already exist in the Volume Location +Database (VLDB), and the -server and -partition +arguments to specify the new volume's site. It is best to omit the +-id argument so that the Volume Location (VL) Server allocates a +volume ID automatically. Do not include the -overwrite +argument, because there is no existing volume to overwrite. +
To overwrite an existing volume at its current site, specify its name and +site with the -name, -server, and -partition +arguments. The volume retains its current volume ID number unless the +-id argument is provided. Specify the value f or +i for the -overwrite argument to indicate whether the +dump file is full or incremental, respectively. +
To overwrite an existing volume and move it to a new site, specify its +name and the new site with the -name, -server, and +-partition arguments. The volume retains its current volume +ID number unless the -id argument is provided. The volume is +removed from its original site. Specify the value f for the +-overwrite argument to indicate that the dump file is a full dump +(it is not possible to restore an incremental dump and move the volume at the +same time). +

If the volume named by the -name argument already exists and the +-overwrite argument is omitted, the command interpreter produces +the following prompt: +

   Do you want to do a full/incremental restore or abort? [fia](a):
+   
+

Respond by entering one of the following values: +

f if restoring a full dump file +
i if restoring an incremental dump file +
a or <Return> to cancel the restore operation +

Cautions +

If the -file argument is omitted, the issuer must provide all +other necessary arguments, because the standard input stream is unavailable +for responding to the command interpreter's prompts for missing +information. In particular, the issuer must provide the +-overwrite argument if overwriting an existing volume. +

Options +

-server +

Identifies the file server machine onto which to restore the +volume. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +

-partition +

Identifies the partition (on the file server machine specified by the +-server argument) onto which to restore the volume. Provide +the partition's complete name with preceding slash (for example, +/vicepa) or use one of the three acceptable abbreviated +forms. For details, see the introductory reference page for the +vos command suite. +

-name +

Specifies the name under which to restore the volume. It can be up +to 22 characters long, but cannot end with a .readonly or +.backup extension. If the volume already exists, it +is overwritten subject to the value of the -overwrite +argument. +

-file +

Names the dump file to restore. Incomplete pathnames are +interpreted relative to the current working directory. Omit this +argument to provide the dump file via the standard input stream. +

-id +

Specifies the volume ID number to assign to the restored volume. +

-overwrite +

Specifies which type of dump file is being restored when overwriting an +existing volume. Provide one of the following values: +

a to terminate the restore operation. +
f if restoring a full dump file. +
i if restoring an incremental dump file. This value is +not acceptable if the -server and -partition arguments +do not indicate the volume's current site. +

This argument is mandatory if the -file argument is not +provided. +

-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 vos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +

-localauth +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command restores the contents of the dump file +/afs/abc.com/common/dumps/terry.dump to the +/vicepc partition on the file server machine +fs3.abc.com. The restored volume is named +user.terry. +

   % cd /afs/abc.com/common/dumps
+   
+   % vos restore -file terry.dump -server fs3.abc.com -partition c  \
+                 -name user.terry
+   
+

Privilege Required +

Related Information +

vos +

vos dump +

vos listvol +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf275.htm b/doc/html/AdminReference/auarf275.htm new file mode 100644 index 0000000..01d2b35 --- /dev/null +++ b/doc/html/AdminReference/auarf275.htm @@ -0,0 +1,143 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos status

+ + + + + +

Purpose +

Reports a Volume Server's status +

Synopsis +

vos status -server <machine name>  [-cell <cell name>]  [-noauth]
+           [-localauth]  [-verbose]  [-help]
+    
+vos st -s <machine name>  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos status command reports on what the Volume Server on a +certain file server machine is doing at the moment the command is +issued. If there is no activity, the following message appears: +

   No active transactions on machine_name
+   
+

This command is useful mainly if there is concern that the Volume Server is +not performing requested actions. +

Options +

-server +: Identifies the file server machine running the Volume Server for which to +display status information. Provide the machine's IP address or +its host name (either fully qualified or using an unambiguous +abbreviation). For details, see the introductory reference page for the +vos command suite. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Output +

There are two possible types of output. +

The following message indicates that the Volume Server is not currently +performing any actions. +

   No active transactions on machine name
+   
+

The other possible output is a set of information which is probably more +useful to programmers than to system administrators. A full +understanding of all the fields requires familiarity with the code for the +Volume Server, as many of the fields report ID numbers and flag values that +the Volume Server sets for internal use. +

Among the fields of possible interest to an administrator are: +

created on the first line, which indicates the time at which +this transaction started +
attachFlags on the second line, where a value of +offline indicates that the volume is not available for other read +or write operations during this transaction +
volume on the third line, which specifies the affected +volume's ID number +
partition on the third line, which indicates where the affected +volume resides (at the beginning of the transaction if this is a move) +
procedure on the third line, which indicates the internal +subprocedure being executed +

A fourth line can appear during certain transactions, and includes the +following fields: +

packetRead tracks whether information is being read into the +volume. Its absolute value is not informative, but the way it changes +shows whether the vos restore command is executing properly. +As the vos status command is issued repeatedly during a restore, +readNext increases monotonically to indicate that information is +being read into the volume. +
packetSend tracks whether information is being sent out of the +volume. Its absolute value is not informative, but the way it changes +shows whether the vos dump command is executing properly. As +the vos status command is issued repeatedly during a dump, +transmitNext increases monotonically to indicate that information +is being transferred from the volume into the dump file. +

The lastReceiveTime and lastSendTime are for internal +use. +

Examples +

The following example illustrates the kind of output that sometimes appears +when the Volume Server on fs1.abc.com is executing a +dump at the time this command is issued. +

   % vos status fs1.abc.com
+   --------------------------------------------
+   transaction: 575  created: Tue Jan 2 8:34:56 1990
+   attachFlags: offline
+   volume: 536871080 partition: /vicepb procedure: Dump
+   packetRead: 2 lastReceiveTime: 113313 packetSend: 24588
+       lastSendTime: 113317
+   --------------------------------------------
+   
+

Privilege Required +

None +

Related Information +

vos +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf276.htm b/doc/html/AdminReference/auarf276.htm new file mode 100644 index 0000000..995c5a3 --- /dev/null +++ b/doc/html/AdminReference/auarf276.htm @@ -0,0 +1,114 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos syncserv

+ + + + + + + + +

Purpose +

Verifies VLDB entries that mention a specified site +

Synopsis +

vos syncserv -server <machine name>  [-partition <partition name>] 
+             [-cell <cell name>]  [-noauth]  [-localauth]  
+             [-verbose]  [-help]
+   
+vos syncs -s <machine name>  [-p <partition name>]  
+          [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos syncserv command verifies that each volume mentioned in +a VLDB entry actually exists at the site indicated in the entry. It +checks all VLDB entries that mention a read/write, read-only, or backup site +either on any partition on the file server machine specified by the +-server argument, or on the one partition specified by the +-server and -partition arguments. Note that the +command can end up inspecting sites other than those specified by the +-server and -partition arguments, if there are versions +of the volume at sites other than the one specified. +

To achieve complete VLDB consistency, first run the vos syncvldb +command on all file server machines in the cell, then run this command on all +file server machines in the cell. +

Options +

-server +: Identifies the file server machine mentioned in each VLDB entry to +check. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +
-partition +: Identifies the partition mentioned in each VLDB entry to check. +Provide the partition's complete name with preceding slash (for example, +/vicepa) or use one of the three acceptable abbreviated +forms. For details, see the introductory reference page for the +vos command suite. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example verifies the VLDB entries in which a site definition +mentions the file server machine fs3.abc.com. +

   % vos syncserv -server fs3.abc.com
+   
+

Privilege Required +

Related Information +

vos +

vos syncvldb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf277.htm b/doc/html/AdminReference/auarf277.htm new file mode 100644 index 0000000..cc82a56 --- /dev/null +++ b/doc/html/AdminReference/auarf277.htm @@ -0,0 +1,136 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos syncvldb

+ + + + + + + + + +

Purpose +

Verifies VLDB entries for volumes residing at specified site +

Synopsis +

vos syncvldb [-server <machine name>]  [-partition <partition name>] 
+             [-volume <volume name or ID>]  [-cell <cell name>]  [-noauth]  
+             [-localauth]  [-verbose]  [-help]
+    
+vos syncv [-s <machine name>]  [-p <partition name>]  [-vo <volume name or ID>] 
+          [-c <cell name>]  [-n]  [-l]  [-ve]  [-h]
+

Description +

The vos syncvldb command verifies that the status of the volumes +housed either on all partitions on the file server machine specified by the +-server argument, or on the single partition specified by the +-server and -partition arguments, is recorded correctly +in the VLDB. If the -volume argument is included to indicate +a single volume, the command compares only its status on the file server +machine with its VLDB entry. +

If the -volume argument is not included, the command interpreter +obtains from the Volume Server a list of the volumes that reside on each +partition, then changes information in the VLDB as necessary to reflect their +state on the partition. For example, it creates or updates a VLDB entry +when it finds a volume for which the VLDB entry is missing or +incomplete. However, if there is already a VLDB entry that defines a +different location for the volume, or there are irreconcilable conflicts with +other VLDB entries, it instead writes a message about the conflict to the +standard error stream. The command never removes volumes from the file +server machine. +

To achieve complete VLDB consistency, run this command on all file server +machines in the cell, and then run the vos syncserv command on all +file server machines in the cell. +

Using the -volume argument basically combines the effects of +this command with those of the vos syncserv command, for a single +volume. The command not only verifies that the VLDB entry is correct +for the specified volume type (read/write, backup, or read-only), but also +checks that any related volume types mentioned in the VLDB entry actually +exist at the site listed in the entry. It is not necessary to provide +the -server argument (and optionally, -partition +argument); if one or both is provided, the results are reliable only if +they specify the actual location of the volume indicated by the +-volume argument. +

Options +

-server +: Identifies the file server machine housing the volumes for which to verify +VLDB entries. Provide the machine's IP address or its host name +(either fully qualified or using an unambiguous abbreviation). For +details, see the introductory reference page for the vos command +suite. +
-partition +: Identifies the partition housing the volumes for which to verify VLDB +entries. Provide the -server argument along with this +one. Provide the partition's complete name with preceding slash +(for example, /vicepa) or use one of the three acceptable +abbreviated forms. For details, see the introductory reference page for +the vos command suite. +
-volume +: Specifies the name or volume ID number of a single volume for which to +verify the VLDB entry. This argument can be combined with the +-server (and optionally, the -partition) +argument. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example command verifies the VLDB entry for each volume +stored on the file server machine fs4.abc.com. +

   % vos syncvldb fs4.abc.com
+   
+

Privilege Required +

Related Information +

vos +

vos syncserv +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf278.htm b/doc/html/AdminReference/auarf278.htm new file mode 100644 index 0000000..d317500 --- /dev/null +++ b/doc/html/AdminReference/auarf278.htm @@ -0,0 +1,97 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos unlock

+ + + + +

Purpose +

Unlocks a single VLDB entry +

Synopsis +

vos unlock -id <volume name or ID>  [-cell <cell name>]  [-noauth] 
+           [-localauth]  [-verbose]  [-help]
+    
+vos unlock -i <volume name or ID>  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos unlock command releases the lock on the Volume Location +Database (VLDB) entry for the indicated volume. +

Cautions +

Do not user this command under normal circumstances. +

It is useful if the VLDB entry is locked but there is no reason to suspect +inconsistency within the volume or between it and the VLDB. Note that +it is possible to list information from locked VLDB entries, even though they +cannot be manipulated in other ways. +

The vos unlockvldb command unlocks several VLDB entries at once, +or even the entire VLDB. The vos lock command locks a VLDB +entry so that no one else can perform an action that requires writing the +VLDB. +

Options +

-id +: Specifies either the complete name or volume ID number of a volume of any +of the three types. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example unlocks the VLDB entry for the volume +user.terry. +

   % vos unlock user.terry
+   
+

Privilege Required +

Related Information +

vos +

vos lock +

vos unlockvldb +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf279.htm b/doc/html/AdminReference/auarf279.htm new file mode 100644 index 0000000..416c297 --- /dev/null +++ b/doc/html/AdminReference/auarf279.htm @@ -0,0 +1,129 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos unlockvldb

+ + + + +

Purpose +

Unlocks several locked VLDB entries +

Synopsis +

vos unlockvldb [-server <machine name>]  [-partition <partition name>] 
+               [-cell <cell name>]  [-noauth]  [-localauth]
+               [-verbose]  [-help]
+    
+vos unlockv [-s <machine name>]  [-p <partition name>]  
+            [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos unlockvldb command releases the lock on the Volume +Location Database (VLDB) entries indicated by the combination of arguments +provided: +

To unlock all entries in the VLDB, provide no arguments +
To unlock all entries that mention a file server machine in a site +definition, provide its name with the -server argument +
To unlock all entries that mention a partition on any file server machine +in a site definition, provide the partition name with the +-partition argument +
To unlock all entries that mention a specific site, provide both the +-server and -partition arguments. +

To unlock a single volume, use the vos unlock command +instead. +

Cautions +

Do not use this command under normal circumstances. +

It is useful if VLDB entries for volumes at a certain site are locked but +there is no reason to suspect inconsistency within the volume or between it +and the VLDB. Note that it is possible to list information from locked +VLDB entries, even though they cannot be manipulated in other ways. +

The vos lock command locks a VLDB entry so that no one else can +perform an action that requires writing the VLDB. +

Options +

-server +: Identifies the file server machine for which to unlock VLDB +entries. Provide the machine's IP address or its host name (either +fully qualified or using an unambiguous abbreviation). For details, see +the introductory reference page for the vos command suite. +
-partition +: Identifies the partition (on the file server machine specified by the +-server argument) for which to unlock VLDB entries. Provide +the partition's complete name with preceding slash (for example, +/vicepa) or use one of the three acceptable abbreviated +forms. For details, see the introductory reference page for the +vos command suite. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following command unlocks all locked entries in the VLDB. +

   % vos unlockvldb
+   
+

The following command unlocks all locked VLDB entries that mention the +/vicepa partition in a site definition. +

   % vos unlockvldb -partition a
+   
+

The following command unlocks all locked VLDB entries that refer to volumes +on the /vicepc partition of the file server machine +fs3.abc.com. +

   % vos unlockvldb -server fs3.abc.com -partition c
+   
+

Privilege Required +

Related Information +

vos +

vos lock +

vos unlock +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf280.htm b/doc/html/AdminReference/auarf280.htm new file mode 100644 index 0000000..ca2daeb --- /dev/null +++ b/doc/html/AdminReference/auarf280.htm @@ -0,0 +1,148 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

vos zap

+ + + + +

Purpose +

Removes a volume from its site without writing to the VLDB +

Synopsis +

vos zap -server <machine name>  -partition <partition name> 
+        -id <volume ID>  [-force]  [-backup]  [-cell <cell name>]
+        [-noauth]  [-localauth]  [-verbose]  [-help]
+    
+vos z -s <machine name>  -p <partition name>  -i <volume ID>
+      [-f]  [-b]  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]
+

Description +

The vos zap command removes the volume with the specified +volume ID from the site defined by the -server and +-partition arguments, without attempting to change the +corresponding Volume Location Database (VLDB) entry. If removing the +volume can possibly result in incorrect data in the VLDB, a warning message is +displayed. +

The -force flag removes a volume even if it cannot be "attached" +(brought online), which can happen either because the volume is extremely +damaged or because the Salvager functioned abnormally. Without this +flag, this command cannot remove volumes that are not attachable. See +also the Cautions section. +

To remove the specified read/write volume's backup version at the same +time, include the -backup flag. +

Cautions +

Do not use this command as the standard way to remove a volume, as it is +likely to put the VLDB out of sync with the volumes on servers. Use the +vos remove command instead. +

This command is useful in situations where it is important to delete the +volume, but for some reason the VLDB is unreachable--for example, because +s the Volume Location Server is unavailable. The issuer can remove the +VLDB entry later with the vos remove or vos delentry +command, or it is removed automatically when the vos syncserv and +vos syncvldb commands run. +

To remove a read-only site defined in the VLDB by mistake, before a copy +actually exists at the site, use the vos remsite command. To +remove an entire VLDB entry without affecting volumes at their sites, use the +vos delentry command. +

Do not use the -force flag if the volume is online, but only +when attempts to remove the volume with the vos remove or the +vos zap command have failed, or the volume definitely cannot be +attached. After using the -force flag, make sure that the +volume's VLDB entry is also removed (issue the vos delentry +command if necessary). +

Adding the -force flag makes the command take considerably +longer--about as long as a salvage of the relevant partition--since +the Volume Server examines all inodes on the partition for traces of the +volume. +

Options +

-server +: Identifies the file server machine from which to remove the volume. +Provide the machine's IP address or its host name (either fully qualified +or using an unambiguous abbreviation). For details, see the +introductory reference page for the vos command suite. +
-partition +: Identifies the partition (on the file server machine specified by the +-server argument) from which to remove the volume. Provide +the partition's complete name with preceding slash (for example, +/vicepa) or use one of the three acceptable abbreviated +forms. For details, see the introductory reference page for the +vos command suite. +
-id +: Specifies the volume ID number of the volume to remove, which can be of +any of the three types. The volume name is not acceptable. +
-force +: Removes the volume even though it cannot be attached (brought +online). Use only after the failure of previous attempts to remove the +volume by using the vos remove command or the vos +command without this flag. +
-backup +: Removes the backup version of the read/write volume specified by the +-id argument. Do not use this flag if the -id +argument identifies a read-only or backup volume. +
-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 vos reference page. +
-noauth +: Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +
-localauth +: Constructs a server ticket using a key from the local +/usr/afs/etc/KeyFile file. The vos command +interpreter presents it to the Volume Server and Volume Location Server during +mutual authentication. Do not combine this flag with the +-cell argument or -noauth flag. For more details, +see the introductory vos reference page. +
-verbose +: Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +
-help +: Prints the online help for this command. All other valid options +are ignored. +

Examples +

The following example removes the volume with volume ID 536870988 from the +/vicepf partition of the file server machine +fs6.abc.com, without noting the change in the +VLDB. +

   % vos zap -server fs6.abc.com -partition f -id 536870988
+   
+

Privilege Required +

Related Information +

vos +

vos delentry +

vos remsite +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf281.htm b/doc/html/AdminReference/auarf281.htm new file mode 100644 index 0000000..1bddcec --- /dev/null +++ b/doc/html/AdminReference/auarf281.htm @@ -0,0 +1,60 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

xfs_size_check

+ + +

Purpose +

Verifies proper inode configuration +

Synopsis +

xfs_size_check
+

Description +

The xfs_size_check command, when run on a file server machine +that runs IRIX version 6.2 or higher and uses XFS-formatted partitions +as server partitions (conventionally mounted at /vicep +directories), verifies that each partition uses 512-byte inodes. AFS +stores information in the inodes on server partitions, and the 256-byte inode +size that XFS uses by default is not large enough. +

Cautions +

This command is available on in the AFS distribution for IRIX system types +that can use XFS-formatted partitions as server partitions. +

Output +

If all server partitions are properly configured, the command produces no +output. Otherwise, it prints the following header: +

   Need to remake the following partitions:
+   
+

and then the following message for each partition on which to run the IRIX +mkfs command with the indicated options: +

   device: mkfs -t xfs -i size=512 -l size=4000b device
+   
+

where device is in a format like /dev/dsk/dks0d0s0 for +a single disk partition or /dev/xlv/xlv0 for a logical +volume. +

Privilege Required +

The issuer must be logged in as the local superuser root. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf282.htm b/doc/html/AdminReference/auarf282.htm new file mode 100644 index 0000000..8d650ee --- /dev/null +++ b/doc/html/AdminReference/auarf282.htm @@ -0,0 +1,97 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

xstat_cm_test

+ + +

Purpose +

Displays data collections from the Cache Manager +

Synopsis +

xstat_cm_test [initcmd] -cmname <Cache Manager name(s) to monitor>⁺
+              -collID <Collection(s) to fetch>⁺  [-onceonly]  
+              [-frequency <poll frequency, in seconds>]  
+              [-period <data collection time, in minutes>]  [-debug]  [-help]
+   
+xstat_cm_test [i] -cm <Cache Manager name(s) to monitor>⁺
+              -co <Collection(s) to fetch>⁺  [-o]  
+              [-f <poll frequency, in seconds>]  
+              [-p <data collection time, in minutes>]  [-d]  [-h]
+

Description +

The xstat_cm_test command tests the routines in the +libxstat_cm.a library and displays the data collections +associated with the Cache Manager. The command executes in the +foreground. +

The command produces a large volume of output; to save it for later +analysis, direct it to a file. +

Options +

initcmd +

Accommodates the command's use of the AFS command parser, and is +optional. +

-cmname +

Specifies the fully qualified hostname of each client machine for which to +monitor the Cache Manager. +

-collID +

Specifies each data collection to return, which defines the type and +amount of data the command interpreter gathers about the Cache Manager. +Data is returned in a predefined data structure. +

There are three acceptable values: +

0 +: Provides profiling information about the numbers of times different +internal Cache Manager routines were called since the Cache Manager +started. +
1 +: Reports various internal performance statistics related to the Cache +Manager (for example, statistics about how effectively the cache is being used +and the quantity of intracell and intercell data access). +
2 +: Reports all of the internal performance statistics provided by the +1 setting, plus some additional, detailed performance figures (for +example, statistics about the number of RPCs sent by the Cache Manager and how +long they take to complete, and statistics regarding authentication, access, +and PAG information associated with data access). +

-onceonly +

Gathers statistics just one time. Omit this flag to have the +command continue to probe the Cache Manager for statistics at the frequency +specified by the -frequency argument; in this case press +<Ctrl-c> to stop the probes. +

-frequency +

Sets the frequency in seconds at which the program initiates probes to the +Cache Manager. The default is 30 seconds. +

-period +

Sets the number of minutes the program runs; at the end of this +period of time, the program exits. The default is 10 minutes. +

-debug +

Displays a trace on the standard output stream as the command runs. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Related Information +

xstat_fs_test +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf283.htm b/doc/html/AdminReference/auarf283.htm new file mode 100644 index 0000000..b13ddf6 --- /dev/null +++ b/doc/html/AdminReference/auarf283.htm @@ -0,0 +1,96 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

xstat_fs_test

+ + +

Purpose +

Displays data collections from the File Server process +

Synopsis +

xstat_fs_test [initcmd] -fsname <File Server name(s) to monitor>⁺
+              -collID <Collection(s) to fetch>⁺  [-onceonly]
+              [-frequency <poll frequency, in seconds>]
+              [-period <data collection time, in minutes>]  [-debug] [-help]
+   
+xstat_fs_test [initcmd] -fs <File Server name(s) to monitor>⁺
+              -c <Collection(s) to fetch>⁺  [-o]
+              [-fr <poll frequency, in seconds>]
+              [-p <data collection time, in minutes>]  [-d] [-h]
+

Description +

The xstat_fs_test command tests the routines in the +libxstat_fs.a library and displays the data collections +associated with the File Server (the fs process). The +command executes in the foreground. +

The command produces a large volume of output; to save it for later +analysis, direct it to a file. +

Options +

initcmd +

Accommodates the command's use of the AFS command parser, and is +optional. +

-fsname +

Specifies the fully qualified hostname of each file server machine for +which to monitor the File Server process. +

-collID +

Specifies each data collection to return, which defines the type and +amount of data the command interpreter gathers about the File Server. +Data is returned in a predefined data structure. +

There are three acceptable values: +

0 +: Provides profiling information about the numbers of times different +internal File Server routines were called since the File Server +started. This value is not currently implemented; it returns no +data. +
1 +: Reports various internal performance statistics related to the File Server +(for example, vnode cache entries and Rx protocol activity). +
2 +: Reports all of the internal performance statistics provided by the +1 setting, plus some additional, detailed performance figures about +the File Server (for example, minimum, maximum, and cumulative statistics +regarding File Server RPCs, how long they take to complete, and how many +succeed). +

-onceonly +

-frequency +

Sets the frequency in seconds at which the program initiates probes to the +Cache Manager. The default is 30 seconds. +

-period +

Sets the number of minutes the program runs; at the end of this +period of time, the program exits. The default is 10 minutes. +

-debug +

Displays a trace on the standard output stream as the command runs. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Related Information +

xstat_cm_test +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/AdminReference/auarf284.htm b/doc/html/AdminReference/auarf284.htm new file mode 100644 index 0000000..f3be594 --- /dev/null +++ b/doc/html/AdminReference/auarf284.htm @@ -0,0 +1,4966 @@ + + +Administration Reference + + + + + + + + + + + +

Administration Reference

Index

+A +B +C +D +E +F +G +H +I +J +K +L +M +N +O +P +Q +R +S +T +U +V +W +X +

+A + +

A instruction + +

uss template file +(4119) +

access + +

count, in volume header +(5683), (5759) +

access control list + +

see entry: ACL +(5222) +

ACL + +

adding entries +(4925) +

all shorthand notation +(4938) +

cleaning +(4747) +

clearing +(4927) +

copying +(4753) +

default set by vos create command +(5625) +

defined +(5221) +

displaying +(4854) +

none shorthand notation +(4942) +

read shorthand notation +(4944) +

removing entries +(4926) +

removing obsolete AFS UIDs +(4746) +

setting +(4924) +

setting with uss +(4127), (4179) +

shorthand notation for permissions +(4939) +

write shorthand notation +(4946) +

active clients statistic in scout +(5462) +

add instruction in uss bulk input file +(4103) +

adding + +

ACL permissions entry +(4930) +

database server machine to CellServDB file (server) +(4453) +

dump level to Backup System dump hierarchy +(4222) +

privileged user to UserList file +(4466) +

read-only site definition in VLDB +(5590) +

server encryption key to KeyFile file +(4456) +

Tape Coordinator entry to Backup Database +(4237) +

user or machine to group +(5237) +

volume entry to volume set in Backup Database +(4245), (4252) +

volume set definition to Backup Database +(4260) +

admin argument + +

on uss commands +(5510) +

ADMIN flag in Authentication Database entry +(5061), (5143) +

administrative file + +

see entry: files +(3863) +

admin_username argument + +

on all kas commands +(5064) +

AFS Backup System + +

see entry: Backup System +(4207) +

AFS GID (group ID) + +

assigning to group +(5267) +

learning given group name +(5326) +

AFS server process + +

see entry: server process +(4440) +

AFS tape name + +

see entry: tape (Backup System) +(4355) +

AFS UID + +

assigning in uss +(5528) +

assigning to user or machine with pts createuser command +(5286) +

displaying +(5341) +

learning given user/machine name +(5325) +

removing obsolete from ACL +(4750) +

afsd command +(4184) +

afsmonitor + +

configuration file +(4036) +

afsmonitor program + +

initialization command +(4193) +

setting terminal type +(4200) +

afszcm.cat file +(4005) +

all shorthand notation for ACL permissions +(4937) +

all-or-nothing release of read-only volumes +(5795) +

appended dump + +

displaying record for +(4323) +

see entry: dump +(4311) +

ASK instruction in CFG_device_name file +(3905) +

assigning + +

AFS GID to group +(5271) +

AFS UID to user +(5290) +

at-sys (@sys) variable in pathnames +(4998), (5472) +

authenticated identity + +

acquiring on NFS client of non-supported type +(5185) +

acquiring with klog +(5182) +

discarding while in kas interactive mode +(5123) +

authentication + +

imposing restrictions with kas +(5142) +

imposing restrictions with uss template A instruction +(4118) +

Authentication Database + +

changing/setting password in +(5191) +

creating entry +(5076) +

deleting entry +(5081) +

displaying all entries +(5115) +

displaying entry +(5085) +

displaying key +(5086) +

entry, creating with uss +(5527) +

entry, deleting with uss +(5551) +

files constituting +(4015) +

information in +(5099) +

setting flags and expiration dates +(5133) +

setting key field using password +(5150) +

setting password in +(5151) +

status, verifying +(5056) +

Authentication Server + +

displaying statistics +(5159) +

displaying traces of privileged actions +(5175) +

listed in client CellServDB file +(3914) +

listed in server CellServDB file +(3922) +

log file +(3870) +

log files for privileged actions +(3873) +

starting +(5172) +

unlocking locked user account +(5169) +

AuthLog file +(3868) +

AuthLog.dir and AuthLog.pag files +(3871) +

authorization checking + +

NoAuth file +(3966) +

setting requirements on server machine +(4617) +

automatic restart times for BOS Server + +

see entry: restart times for BOS Server +(4541) +

AUTOQUERY instruction in CFG_device_name file +(3906) +

availability of data + +

interrupted by dumping +(5649) +

+B + +

B instruction + +

package configuration file +(4041) +

backup + +

see entry: backup commands +(4206) +

see entry: Backup System +(4205) +

backup commands + +

adddump +(4218) +

addhost +(4229) +

addvolentry +(4240), (4247) +

addvolset +(4255) +

apropos +(4261) +

common options +(4211) +

dbverify +(4264) +

deldump +(4267) +

deletedump +(4275) +

delhost +(4281) +

delvolentry +(4286) +

delvolset +(4292) +

diskrestore +(4296) +

dump +(4302) +

dumpinfo +(4316) +

help +(4324) +

interactive +(4327) +

introduction +(4204) +

jobs +(4332) +

kill +(4339) +

labeltape +(4345) +

listdumps +(4357) +

listhosts +(4365) +

listvolsets +(4374) +

privilege requirements +(4217) +

quit +(4380) +

readlabel +(4386) +

restoredb +(4394) +

savedb +(4397) +

scantape +(4400) +

setexp +(4406) +

status +(4412) +

volinfo +(4416) +

volrestore +(4422) +

volsetrestore +(4428) +

Backup Database + +

dump hierarchy, displaying +(4361) +

dump level, creating +(4224) +

dump level, removing +(4271) +

dump record, deleting +(4278) +

dump record, displaying +(4319) +

expiration date, setting on existing dump level +(4409) +

expiration date, setting on new dump level +(4226) +

files constituting +(4010) +

information recorded +(4209) +

port offset number, assigning to Tape Coordinator +(4234) +

port offset number, displaying +(4370) +

restoring from tape +(4396) +

saving to tape +(4399) +

status, verifying +(4266) +

Tape Coordinator entry, creating +(4235) +

Tape Coordinator entry, deleting +(4283) +

Tape Coordinator entry, displaying +(4371) +

volume dump history, displaying +(4418) +

volume entry in volume set, displaying +(4378) +

volume entry, adding to volume set +(4243), (4250) +

volume entry, removing from volume set +(4289) +

volume set, creating +(4258) +

volume set, deleting +(4294) +

volume set, restoring +(4433) +

backup extension on volume name +(5603) + +

added by vos backup command +(5604) +

added by vos backupsys command +(5611) +

Backup field in volume header +(5675), (5751) +

Backup Server + +

initialization command +(4687) +

listed in client CellServDB file +(3917) +

listed in server CellServDB file +(3925) +

log file +(3876), (3879) +

Backup System + +

Backup Server process, starting +(4690) +

database (see entry: Backup Database) +(4208) +

interactive mode, entering +(4331) +

interactive mode, exiting +(4385) +

job ID number, displaying +(4334) +

job ID number, using to halt operation +(4343) +

operations, displaying pending and running +(4335) +

operations, halting in interactive mode +(4341) +

regular expressions +(4254) +

tape capacity, displaying from label +(4391) +

tape capacity, recording on label +(4352) +

Tape Coordinator, initializing +(4696) +

tape, creating label +(4351) +

tape, displaying label +(4390) +

backup volume + +

creating +(5602) +

creating many at once +(5610) +

dumping +(5648) +

ID number +(5637) +

ID number in volume header +(5671), (5747) +

moving +(5774) +

name, changing +(5828) +

removed by read/write move +(5772) +

removed by read/write removal +(5810) +

removing +(5812) +

BackupLog file +(3874) +

BAK version of binary file + +

creation by bos install command +(4554) +

listing time stamp on +(4521) +

removing from /usr/afs/bin directory +(4578) +

use by bos uninstall command +(4678) +

Basic OverSeer Server + +

see entry: BOS Server +(4437) +

bdb.DB0 file +(4006) +

bdb.DBSYS1 file +(4008) +

binary distribution machine +(4552), (4676) +

binary file + +

installing +(4550) +

listing time stamp on +(4519) +

uninstalling +(4674) +

block special device + +

defining with package +(4045) +

bos commands + +

addhost +(4451) +

addkey +(4463) +

adduser +(4471) +

apropos +(4473) +

common options +(4443) +

create +(4485) +

delete +(4509) +

exec +(4513) +

getcell (see entry: listhosts) +(4562) +

getdate +(4516) +

getlog +(4527) +

getrestart +(4543) +

help +(4545) +

install +(4548) +

listhosts +(4561) +

listkeys +(4566) +

listusers +(4573) +

privilege requirements +(4450) +

prune +(4575) +

removehost +(4588) +

removekey +(4596) +

removeuser +(4601) +

restart +(4603) +

salvage +(4615) +

setauth +(4620) +

setcellname +(4622) +

setrestart +(4634) +

shutdown +(4640) +

start +(4644) +

startup +(4652) +

status +(4656) +

stop +(4665) +

uninstall +(4671) +

BOS Server +(4436) + +

memory state +(3894) +

restart times, displaying +(4537) +

restart times, setting +(4631) +

restarting +(4607) +

SALVAGE.fs file, response to +(3971) +

starting +(4682) +

BosConfig file +(3880) + +

creating entry with bos create command +(4484) +

displaying entry with bos status command +(4662) +

removing entry with bos delete command +(4506) +

BosLog file +(3877) +

bosserver command +(4680) +

BUFFERSIZE instruction in CFG_device_name file +(3907) +

bulk input file + +

see entry: uss bulk input file +(4100) +

bulk mode in uss +(5543) +

buserver command +(4685) +

buserver process + +

creating with bos create command +(4487) +

butc command +(4691) +

+C + +

C instruction + +

package configuration file +(4042) +

Cache Manager + +

changing database server machines known to +(4908) +

configuring with afsd +(4189) +

configuring with fs commands +(4716) +

disabling messages +(4890) +

displaying amount of cache used +(4832) +

displaying cache size +(4831) +

displaying database server machines known to +(4862) +

displaying inaccessible server machines +(4734) +

displaying server machine preference ranks +(4846) +

flushing directory/file from data cache +(4808) +

flushing entire volume from data cache +(4821) +

flushing mount point from data cache +(4815) +

initializing with afsd +(4188) +

interfaces not registered with File Server, setting +(3956) +

interfaces registered with File Server, displaying +(4841) +

interfaces registered with File Server, setting +(3945), (4963) +

logging messages +(4889) +

monitoring status with afsmonitor +(4196) +

NetInfo file +(3944) +

NetRestrict file +(3955) +

setting cache size +(4952) +

setting server machine preference ranks +(4973) +

setting the interval between server probes +(4735) +

volume name to ID mapping, forcing update of +(4739) +

VolumeItems file +(4002) +

cache-related file + +

see entry: files +(3864) +

CacheItems file +(3897) +

cell + +

client +(4864), (4906) +

database server machines listed in client CellServDB file +(3919) +

database server machines listed in server CellServDB file +(3927) +

membership of client machine +(3977) +

membership of server machine +(3982) +

name, setting +(4628) +

setuid status, displaying +(4835) +

setuid status, setting +(4955) +

cell argument + +

on backup commands +(4212) +

on bos commands +(4444) +

on kas commands +(5065) +

on pts commands +(5231) +

on uss commands +(5511) +

on vos commands +(5578) +

CellServDB file (client version) +(3912) + +

displaying contents as copied into kernel memory +(4865) +

CellServDB file (server version) +(3920) + +

adding entry with bos addhost command +(4454) +

creating with bos setcellname command +(4623) +

displaying contents with bos listhosts command +(4558) +

removing entry with bos removehost command +(4590) +

cellular mount point +(4902) +

CFG_device_name file +(3900) +

changing + +

data cache size +(4947) +

database server machines listed in client kernel +(4905) +

name of Protection Database entry +(5393) +

owner of Protection Database entry +(5251) +

password in Authentication Database +(5189) +

volume name +(5824) +

volume quota +(4967) +

character special device + +

defining with package +(4052) +

character string + +

converting to octal key form +(5164) +

checking + +

AFS client as exporter non-AFS file system +(4800) +

server machine status +(4731) +

cleaning + +

ACL +(4748) +

clearing + +

ACL +(4932) +

client machine + +

as exporter of non-AFS file system +(4802) +

cell membership +(3978) +

changing database server machines known to +(4909) +

changing size of data cache +(4951) +

configuring local disk with package +(5200) +

displaying database server machines known to +(4863) +

displaying home cell of +(5018) +

displaying system type +(4989), (5470) +

setting system type +(4993) +

client machines statistic in scout +(5463) +

client portion of Update Server + +

see entry: upclient process +(5500) +

clone +(5785) + +

forcing creation of new +(5802) +

cloning + +

for backup +(5599), (5608) +

volume for replication +(5790) +

commands + +

afsd +(4185) +

afsmonitor +(4194) +

backup (introduction) +(4203) +

backup adddump +(4219) +

backup addhost +(4230) +

backup addvolentry +(4239), (4246) +

backup addvolset +(4256) +

backup apropos +(4262) +

backup dbverify +(4265) +

backup deldump +(4268) +

backup deletedump +(4276) +

backup delhost +(4280) +

backup delvolentry +(4285) +

backup delvolset +(4291) +

backup diskrestore +(4297) +

backup dump +(4303) +

backup dumpinfo +(4317) +

backup help +(4325) +

backup interactive +(4328) +

backup jobs +(4333) +

backup kill +(4340) +

backup labeltape +(4346) +

backup listdumps +(4358) +

backup listhosts +(4366) +

backup listvolsets +(4375) +

backup quit +(4381) +

backup readlabel +(4387) +

backup restoredb +(4395) +

backup savedb +(4398) +

backup scantape +(4401) +

backup setexp +(4407) +

backup status +(4413) +

backup volinfo +(4417) +

backup volrestore +(4423) +

backup volsetrestore +(4429) +

bos (introduction) +(4435) +

bos addhost +(4452) +

bos addkey +(4464) +

bos adduser +(4472) +

bos apropos +(4474) +

bos create +(4486) +

bos delete +(4510) +

bos exec +(4514) +

bos getdate +(4520) +

bos getlog +(4528) +

bos getrestart +(4544) +

bos help +(4546) +

bos install +(4553) +

bos listhosts +(4560) +

bos listkeys +(4567) +

bos listusers +(4574) +

bos prune +(4582) +

bos removehost +(4592) +

bos removekey +(4597) +

bos removeuser +(4602) +

bos restart +(4608) +

bos salvage +(4616) +

bos setauth +(4621) +

bos setcellname +(4629) +

bos setrestart +(4635) +

bos shutdown +(4641) +

bos start +(4649) +

bos startup +(4655) +

bos status +(4660) +

bos stop +(4670) +

bos uninstall +(4677) +

bosserver +(4681) +

buserver +(4686) +

butc +(4692) +

dlog +(4698) +

dpass +(4700) +

executing remotely +(4512) +

fileserver +(4702) +

fms +(4706) +

fs apropos +(4726) +

fs checkservers +(4729) +

fs checkvolumes +(4737) +

fs cleanacl +(4752) +

fs copyacl +(4756) +

fs diskfree +(4771) +

fs examine +(4795) +

fs exportafs +(4797) +

fs flush +(4812) +

fs flushmount +(4818) +

fs flushvolume +(4824) +

fs getcacheparms +(4826) +

fs getcellstatus +(4834) +

fs getclientaddrs +(4840) +

fs getserverprefs +(4845) +

fs help +(4852) +

fs listacl +(4859) +

fs listcells +(4868) +

fs listquota +(4870) +

fs lsmount +(4888) +

fs messages +(4892) +

fs mkmount +(4897) +

fs newcell +(4912) +

fs quota +(4914) +

fs rmmount +(4923) +

fs setacl +(4936) +

fs setcachesize +(4954) +

fs setcell +(4960) +

fs setclientaddrs +(4962) +

fs setquota +(4970) +

fs setserverprefs +(4972) +

fs setvol +(4984) +

fs storebehind +(4985) +

fs sysname +(4988) +

fs whereis +(5007) +

fs whichcell +(5014) +

fs wscell +(5020) +

fstrace (introduction) +(5026) +

fstrace apropos +(5029) +

fstrace dump +(5032) +

fstrace help +(5034) +

fstrace lslog +(5037) +

fstrace lsset +(5039) +

fstrace setlog +(5041) +

fstrace setset +(5043) +

ftpd (AFS version) +(5045) +

inetd (AFS version) +(5050) +

kadb_check +(5055) +

kas apropos +(5071) +

kas create +(5074) +

kas delete +(5079) +

kas examine +(5083) +

kas forgetticket +(5105) +

kas help +(5110) +

kas list +(5113) +

kas listtickets +(5117) +

kas noauthentication +(5120) +

kas quit +(5125) +

kas setfields +(5131) +

kas setpassword +(5148) +

kas statistics +(5156) +

kas stringtokey +(5162) +

kas unlock +(5168) +

kaserver +(5171) +

kdb +(5174) +

klog +(5177) +

knfs +(5184) +

kpasswd +(5188) +

kpwvalid +(5195) +

package +(5198) +

package apropos +(5205) +

package help +(5208) +

package_test +(5211) +

pagsh +(5214) +

prdb_check +(5218) +

pts adduser +(5236) +

pts apropos +(5245) +

pts chown +(5248) +

pts creategroup +(5253) +

pts createuser +(5275) +

pts delete +(5294) +

pts examine +(5304) +

pts help +(5351) +

pts listentries +(5354) +

pts listmax +(5360) +

pts listowned +(5368) +

pts membership +(5375) +

pts removeuser +(5383) +

pts rename +(5391) +

pts setfields +(5397) +

pts setmax +(5410) +

ptserver +(5418) +

rcp (AFS version) +(5423) +

rsh (AFS version) +(5429) +

runntp +(5434) +

rxdebug +(5441) +

salvager +(5443) +

scout +(5448) +

sys +(5469) +

tokens +(5478) +

translate_et +(5482) +

udebug +(5485) +

unlog +(5488) +

up +(5494) +

upclient +(5498) +

upserver +(5504) +

uss add +(5518) +

uss apropos +(5537) +

uss bulk +(5540) +

uss delete +(5544) +

uss help +(5555) +

vldb_check +(5558) +

vlserver +(5561) +

volinfo +(5565) +

volserver +(5567) +

vos (introduction) +(5569) +

vos addsite +(5588) +

vos apropos +(5594) +

vos backup +(5597) +

vos backupsys +(5606) +

vos changeaddr +(5613) +

vos create +(5615) +

vos delentry +(5639) +

vos dump +(5643) +

vos examine +(5655) +

vos help +(5696) +

vos listaddrs +(5699) +

vos listpart +(5704) +

vos listvldb +(5709) +

vos listvol +(5730) +

vos lock +(5762) +

vos move +(5767) +

vos partinfo +(5776) +

vos release +(5783) +

vos remove +(5806) +

vos remsite +(5814) +

vos rename +(5820) +

vos restore +(5830) +

vos status +(5834) +

vos syncserv +(5839) +

vos syncvldb +(5847) +

vos unlock +(5856) +

vos unlockvldb +(5860) +

vos zap +(5864) +

xfs_size_check +(5868) +

xstat_cm_test +(5870) +

xstat_fs_test +(5872) +

common options + +

on backup commands +(4210) +

on bos commands +(4442) +

on fs commands +(4720) +

on fstrace commands +(5024) +

on kas commands +(5057) +

on pts commands +(5227) +

on uss commands +(5508) +

on vos commands +(5576) +

configuration file + +

see entry: afsmonitor configuration file +(4037) +

see entry: CFG_<device_name> configuration file +(3904) +

see entry: files +(3862) +

see entry: package configuration file +(4039) +

configuring + +

Cache Manager with afsd +(4187) +

Cache Manager with fs commands +(4718) +

local disk of client with package +(5199) +

connections statistic in scout +(5459) +

contacting + +

file server with fs commands +(4717) +

controller file + +

see entry: files +(3867) +

controlling + +

Cache Manager with fs commands +(4719) +

server process status with entry in BosConfig file +(3883) +

converting + +

character string to octal key form +(5163) +

copying + +

access control list +(4754) +

file remotely with rcp command (AFS version) +(5426) +

files and directories +(5495) +

core files + +

removing from /usr/afs/logs directory +(4581) +

creating + +

Authentication Database entry +(5075) +

Authentication Database entry with uss +(5523) +

backup volume +(5600) +

backup volumes, many at once +(5609) +

buserver process +(4488) +

directory with uss +(4125), (4145) +

dump level in Backup System dump hierarchy +(4221) +

file with uss +(4133), (4139) +

fs process +(4490) +

group in Protection Database +(5255) +

hard link with uss +(4152) +

kaserver process +(4492) +

machine entry in Protection Database +(5279) +

mount point +(4894) +

mount point with uss +(4168) +

PAG with pagsh command +(5216) +

privileged user in UserList file +(4468) +

Protection Database entry with uss +(5522) +

ptserver process +(4494) +

read-only volume +(5789) +

read/write volume +(5616) +

runntp process +(4496) +

server encryption key +(4458) +

server process in BosConfig file +(4479) +

symbolic link with uss +(4158) +

Tape Coordinator entry in Backup Database +(4236) +

ticket (tokens) for server process +(5178) +

upclient process +(4498) +

upserver process +(4500) +

user account with uss +(5520) +

user accounts in bulk +(5541) +

user entry in Protection Database +(5278) +

vlserver process +(4502) +

volume (see type--read/write, etc.) +(5617) +

volume set in Backup Database +(4259) +

volume with uss +(4167), (5524) +

creation date + +

recorded in volume header +(5679), (5755) +

creator + +

Protection Database entry, displaying +(5332) +

cron process + +

creating with bos create command +(4505) +

recorded in BosConfig file +(3886) +

curses graphics utility + +

afsmonitor program +(4198) +

+D + +

D instruction + +

package configuration file +(4056) +

uss template file +(4120) +

daily restart time for new binaries + +

see entry: restart times for BOS Server +(4540) +

data + +

availability interrupted by dumping +(5650) +

data cache + +

changing size of +(4949) +

displaying amount used +(4828) +

displaying size +(4827) +

flushing directory/file +(4806) +

flushing entire volume +(4819) +

flushing mount point +(4813) +

resetting to default size +(4950) +

setting location with afsd +(4191) +

setting size with afsd +(4190) +

database file + +

see entry: files +(3866) +

database server machine + +

adding to CellServDB file (server) +(4455) +

changing client kernel list of +(4907) +

displaying from client kernel +(4861) +

displaying list in CellServDB file (server) +(4559) +

listed in client CellServDB file +(3918) +

listed in server CellServDB file +(3926) +

removing from CellServDB file (server) +(4591) +

date on file + +

see entry: time stamp +(4524) +

date-specific restore + +

see entry: restoring +(4427) +

default + +

ACL for new volume +(5627) +

volume quota +(5628) +

define statement + +

package configuration file +(4085) +

defining + +

block special device with package +(4044) +

capacity of Backup System tape +(4348) +

character special device with package +(4051) +

directory with package +(4059) +

file with package +(4066) +

privileged user in UserList file +(4467) +

read-only site in VLDB +(5589) +

server encryption key +(4457) +

socket with package +(4080) +

symbolic link with package +(4073) +

system type of client machine +(4991) +

delete instruction in uss bulk input file +(4105) +

deleting + +

Authentication Database entry +(5080) +

Authentication Database entry with uss +(5549) +

dump level from Backup Database +(4272) +

dump record from Backup Database +(4279) +

Protection Database entry +(5295) +

Protection Database entry with uss +(5548) +

Quick Beginnings

+AFS
+Quick Beginnings
+

Version 3.6 +

Document Number SC09-4560-00 +

CT6Q7NA +

+
+

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 +

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. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartUnix/auqbg002.htm b/doc/html/QuickStartUnix/auqbg002.htm new file mode 100644 index 0000000..77ed1c0 --- /dev/null +++ b/doc/html/QuickStartUnix/auqbg002.htm @@ -0,0 +1,225 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

About This Guide
+

Organization of the Document +

How to Use This Document +

The Procedures Described in this Guide + +

Installation Overview
+

Required Initial Procedures +

As-needed Procedures +

Quick Beginnings

About This Guide

This section describes the purpose, organization, and conventions of this +document. +

Audience and Purpose

This guide explains how to install and configure +AFS^{^(R)} server and client machines. It assumes that the +reader is familiar with UNIX^{^(R)} system administration, but not +AFS. +

The instructions explain how to issue AFS commands in the context of +specific tasks, but do not describe a command's function or arguments in +detail. Refer to the IBM AFS Administration Reference as +necessary. +

Organization of the Document

See The Procedures Described in this Guide. +

How to Use This Document

See The Procedures Described in this Guide and How to Continue. +

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 + + + + diff --git a/doc/html/QuickStartUnix/auqbg004.htm b/doc/html/QuickStartUnix/auqbg004.htm new file mode 100644 index 0000000..dad0ba4 --- /dev/null +++ b/doc/html/QuickStartUnix/auqbg004.htm @@ -0,0 +1,281 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

Installation Overview

This chapter describes the type of instructions provided in +this guide and the hardware and software requirements for installing +AFS^{^(R)}. +

Before beginning the installation of your cell's first machine, read +this chapter and the material from the IBM AFS Administration Guide +listed in Recommended Reading List. It is also best to read through Installing the First AFS Machine before beginning the installation, so that +you understand the overall scope of the installation procedure. +Similarly, before installing additional server or client machines it is best +to read through Installing Additional Server Machines and Installing Additional Client Machines. +

If you are already running a version of AFS, consult the upgrade +instructions in the IBM AFS Release Notes or contact the AFS +Product Support group before proceeding with the installation. +

The Procedures Described in this Guide

This guide describes two types of installation +procedures: initial procedures (such as installing the first AFS machine +or incorporating AFS into the kernel) and as-needed procedures (such as +installing additional server machines or client machines). +

Required Initial Procedures

You must perform the following basic procedures to start using +AFS. +

Incorporating AFS Into the Kernel

You must incorporate AFS modifications into the kernel of every AFS +file server and client machine. Depending on the operating system, you +either use a program for dynamic kernel loading, build a new static kernel, or +can choose between the two. For your convenience, the instructions for +incorporating AFS into the kernel appear in full in every chapter where you +need to use them. + + +

Installing the First AFS Machine

You install the first AFS machine in your cell to function as both an +AFS server and client machine. You can disable the client functionality +after completing the installation, if you wish. +

The first server machine in a cell performs several functions: +

It acts as the system control machine (if your AFS distribution +includes the required encryption files), distributing certain configuration +files to the other server machines in the cell +
It acts as the binary distribution machine for its system type, +distributing AFS binaries to other server machines of its system type +
It acts as the first database server machine, running the +server processes that maintain the AFS administrative databases +

After you install server and client functionality, you complete other +procedures specific to the first machine, including setting up the top levels +of your cell's AFS filespace. +

As-needed Procedures

Upgrading the Operating System

Upgrading the operating system requires you to take several steps to +protect data and AFS-modified binaries from being lost or overwritten. +For guidelines, see About Upgrading the Operating System. +

Requirements

You must comply with the following requirements to install AFS +successfully. + +

Login Identity

Log into the machine you are installing as the local superuser +root. When instructed, also authenticate with AFS as the +administrative user admin. + + +

General Requirements

You must have the AFS Binary Distribution for each system type you are +installing. Unless otherwise noted, the Binary Distribution includes +software for both client and server machines. If you are using the +CD-ROM version of the distribution, the machine you are installing must be +able to access the CD-ROMs, either through a local CD drive or via an +NFS^{^(R)} mount of a CD drive attached to a machine that is +accessible by network. +
All AFS machines that belong to a cell must be able to access each other +via the network. +
The machine must be running the standard, vendor-supplied version of the +operating system supported by the current version of AFS. The operating +system must already be installed on the machine's root partition. +
You must be familiar with the current operating system and disk +configuration of the machine you are installing. +
All hardware and non-AFS software on the machine must be functioning +normally. +
No critical processes can be running on the machine you are installing, +because you must reboot it during the installation. +

+ + +

File Server Machine Requirements

Cell configuration is simplest if the first machine you install has the +lowest IP address of any database server machine you currently plan to +install. If you later configure a machine with a lower IP address as a +database server machine, you must update the +/usr/vice/etc/CellServDB file on all of your cell's client +machines before the installation. For further discussion, see Installing Database Server Functionality. +
The partition mounted on the /usr directory must have at least +18 MB of disk space available for storing the AFS server binaries (stored by +convention in the /usr/afs/bin directory). If the machine is +also a client, there must be additional local disk space available, as +specified in Client Machine Requirements. The complete set of AFS binaries requires yet more +space, but they are normally stored in an AFS volume rather than on a +machine's local disk. +
More significant amounts of space on the partition are required by the +administrative databases stored in the /usr/afs/db directory and +the server process log files stored in the /usr/afs/logs +directory. The exact requirement depends on many factors, such as the +size of your cell and how often you truncate the log files. +
There must be at least one partition (or logical volume, if the operating +system and AFS support them) dedicated exclusively to storing AFS +volumes. The total number and size of server partitions on all file +server machines in the cell determines how much space is available for AFS +files. +

+ + +

Client Machine Requirements

The partition mounted on the /usr directory must have at least +4 MB of disk space available for storing the AFS client binaries and kernel +library files (stored by convention in the /usr/vice/etc +directory). The complete set of AFS binaries requires more space, but +they are normally stored in an AFS volume rather than on a machine's +local disk. For most system types, the instructions have you copy only +the one kernel library file appropriate for the machine you are +installing. If you choose to store all of the library files on the +local disk, the space requirement can be significantly greater. +
On a client machine that uses a disk cache, there must be enough free +space on the cache partition (by convention, mounted on the +/usr/vice/cache directory) to accommodate the cache. The +minimum recommended cache size is 10 MB, but larger caches generally perform +better. +
On a client machine that uses a memory cache, there must be at least 5 MB +of machine memory to devote to caching, but again more memory generally leads +to better performance. For further discussion, see the sections in Installing Additional Client Machines about configuring the cache. +

+ + +

Supported System Types

The IBM AFS Release Notes for each AFS release +list the supported system types. Support for subsequent revisions of an +operating system often becomes available between AFS releases. The AFS +Product Support group can provide details. +

It is the goal of the AFS Development and Product Support groups to support +AFS on a wide range of popular system types. Furthermore, each time an +operating system vendor releases a new general availability version of a +supported operating system, it is a goal to certify and support AFS on it +within a short time. Support can be delayed a bit longer if it is +necessary to generate completely new binaries. +

It is not always possible to support AFS on every intermediate version of +an operating system or for certain processor types. In some cases, +platform limitations make certain AFS functionality (such as file server or +NFS/AFS translator functionality) unavailable on one or more platforms. +For a list of limitations, see the IBM AFS Release Notes or ask the +AFS Product Support group. + + + + +

About Upgrading the Operating System

Whenever you upgrade an AFS machine to a different operating +system, you must take several actions to maintain proper AFS +functionality. These actions include, but are not necessarily limited +to, the following. +

Unmount the AFS server partitions (mounted at /vicepxx +directories) on all file server machines, to prevent the vendor-supplied +fsck program from running on them when you reboot the machine +during installation of the new operating system. Before upgrading the +operating system, it is prudent to comment out commands in the machine's +initialization file that remount the server partitions, to prevent them from +being remounted until you can replace the standard fsck program +with the AFS-modified version. The instructions in this guide for +installing AFS server machines explain how to replace the fsck +program. +
Protect the AFS-modified versions of commands and configuration files from +being overwritten by vendor-supplied versions. These include +vfsck (the AFS version of fsck), binaries for the UNIX +remote services such as inetd, and configuration files such as the +one for the Pluggable Authentication Module (PAM). After you have +successfully installed the operating system, remember to move the AFS-modified +commands and files back to the locations where they are accessed during normal +functioning. +
Reformat the server partitions to accommodate AFS-specific information, in +certain cases. The upgrade instructions that accompany the new AFS +binaries for an affected platform always detail the required procedure. +

+ + + + +

The AFS Binary Distribution

The AFS Binary Distribution includes a separate CD-ROM for +each supported system type, containing all AFS binaries and files for both +server and client machines. The instructions in this guide specify when +to mount the CD-ROM and which files or directories to copy to the local disk +or into an AFS volume. +

How to Continue

If you are installing the first AFS machine in your cell, +proceed to Installing the First AFS Machine. +

If you are installing an additional file server machine, or configuring or +decommissioning a database server machine, proceed to Installing Additional Server Machines. +

If you are installing an additional client machine, proceed to Installing Additional Client Machines. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartUnix/auqbg005.htm b/doc/html/QuickStartUnix/auqbg005.htm new file mode 100644 index 0000000..8a9aee5 --- /dev/null +++ b/doc/html/QuickStartUnix/auqbg005.htm @@ -0,0 +1,4383 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

+ + + +

Installing the First AFS Machine

This chapter describes how to install the first AFS machine +in your cell, configuring it as both a file server machine and a client +machine. After completing all procedures in this chapter, you can +remove the client functionality if you wish, as described in Removing Client Functionality. +

To install additional file server machines after completing this chapter, +see Installing Additional Server Machines. +

To install additional client machines after completing this chapter, see Installing Additional Client Machines. + +

Requirements and Configuration Decisions

The instructions in this chapter assume that you meet the following +requirements. +

You are logged onto the machine's console as the local superuser +root +
A standard version of one of the operating systems supported by the +current version of AFS is running on the machine +
You can access the data on the AFS CD-ROMs, either through a local CD +drive or via an NFS mount of a CD drive attached to a machine that is +accessible by network +

You must make the following configuration decisions while installing the +first AFS machine. To speed the installation itself, it is best to make +the decisions before beginning. See the chapter in the IBM AFS +Administration Guide about issues in cell administration and +configuration for detailed guidelines. + + + +

Select the first AFS machine +
Select the cell name +
Decide which partitions or logical volumes to configure as AFS server +partitions, and choose the directory names on which to mount them +
Decide whether to use the standard AFS authentication and authorization +software or Kerberos as obtained from another source. On several system +types, the decision determines how you incorporate AFS into the machine's +authentication system. If you wish to use Kerberos, contact the AFS +Product Support group now to learn about how you must modify the installation +procedure. +
Decide how big to make the client cache +
Decide how to configure the top levels of your cell's AFS filespace +

This chapter is divided into three large sections corresponding to the +three parts of installing the first AFS machine. Perform all of the +steps in the order they appear. Each functional section begins with a +summary of the procedures to perform. The sections are as +follows: +

Installing server functionality (begins in Overview: Installing Server Functionality) +
Installing client functionality (begins in Overview: Installing Client Functionality) +
Configuring your cell's filespace, establishing further security +mechanisms, and enabling access to foreign cells (begins in Overview: Completing the Installation of the First AFS Machine) +

+ + + +

Overview: Installing Server Functionality

In the first phase of installing your cell's first AFS +machine, you install file server and database server functionality by +performing the following procedures: +

Choose which machine to install as the first AFS machine +
Create AFS-related directories on the local disk +
Incorporate AFS modifications into the machine's kernel +
Configure partitions or logical volumes for storing AFS volumes +
On some system types, install and configure an AFS-modified version of the +fsck program +
If the machine is to remain a client machine, incorporate AFS into its +authentication system +
Start the Basic OverSeer (BOS) Server +
Define the cell name and the machine's cell membership +
Start the database server processes: Authentication Server, Backup +Server, Protection Server, and Volume Location (VL) Server +
Configure initial security mechanisms +
Start the fs process, which incorporates three component +processes: the File Server, Volume Server, and Salvager +
Start the server portion of the Update Server +
Start the controller process (called runntp) for the Network +Time Protocol Daemon, which synchronizes machine clocks +

Choosing the First AFS Machine

The first AFS machine you install must have sufficient disk +space to store AFS volumes. To take best advantage of AFS's +capabilities, store client-side binaries as well as user files in +volumes. When you later install additional file server machines in your +cell, you can distribute these volumes among the different machines as you see +fit. +

These instructions configure the first AFS machine as a database +server machine, the binary distribution machine for its +system type, and the cell's system control machine. For +a description of these roles, see the IBM AFS Administration +Guide. +

Installation of additional machines is simplest if the first machine has +the lowest IP address of any database server machine you currently plan to +install. If you later install database server functionality on a +machine with a lower IP address, you must first update the +/usr/vice/etc/CellServDB file on all of your cell's client +machines. For more details, see Installing Database Server Functionality. +

Creating AFS Directories

+ + + + + + + + + + + +

Create the /usr/afs and /usr/vice/etc directories on +the local disk, to house server and client files respectively. +Subsequent instructions copy files from the AFS CD-ROM into them. +Create the /cdrom directory as a mount point for CD-ROMs, if it +does not already exist. +

      
+   # mkdir /usr/afs
+      
+   # mkdir /usr/vice
+      
+   # mkdir /usr/vice/etc
+   
+   # mkdir /cdrom 
+     
+

Performing Platform-Specific Procedures

Several of the initial procedures for installing a file +server machine differ for each system type. For convenience, the +following sections group them together for each system type: +

Incorporate AFS modifications into the kernel. +
The kernel on every AFS file server and client machine must incorporate AFS +extensions. On machines that use a dynamic kernel module loader, it is +conventional to alter the machine's initialization script to load the AFS +extensions at each reboot. + + + + + + + +
Configure server partitions or logical volumes to house AFS +volumes. +
Every AFS file server machine must have at least one partition or logical +volume dedicated to storing AFS volumes (for convenience, the documentation +hereafter refers to partitions only). Each server partition is mounted +at a directory named /vicepxx, where xx is one or +two lowercase letters. By convention, the first 26 partitions are +mounted on the directories called /vicepa through +/vicepz, the 27th one is mounted on the /vicepaa +directory, and so on through /vicepaz and /vicepba, +continuing up to the index corresponding to the maximum number of server +partitions supported in the current version of AFS (which is specified in the +IBM AFS Release Notes). +
The /vicepxx directories must reside in the file server +machine's root directory, not in one of its subdirectories (for example, +/usr/vicepa is not an acceptable directory location). +
You can also add or remove server partitions on an existing file server +machine. For instructions, see the chapter in the IBM AFS +Administration Guide about maintaining server machines. +
Note: Not all file system types supported by an operating system are necessarily +supported as AFS server partitions. For possible restrictions, see the +IBM AFS Release Notes. +
+
On some system types, install and configure a modified fsck +program which recognizes the structures that the File Server uses to organize +volume data on AFS server partitions. The fsck program +provided with the operating system does not understand the AFS data +structures, and so removes them to the lost+found directory. +
If the machine is to remain an AFS client machine, modify the +machine's authentication system so that users obtain an AFS token as they +log into the local file system. Using AFS is simpler and more +convenient for your users if you make the modifications on all client +machines. Otherwise, users must perform a two-step login procedure +(login to the local file system and then issue the klog +command). For further discussion of AFS authentication, see the chapter +in the IBM AFS Administration Guide about cell configuration and +administration issues. +

To continue, proceed to the appropriate section: +

Getting Started on AIX Systems +
Getting Started on Digital UNIX Systems +
Getting Started on HP-UX Systems +
Getting Started on IRIX Systems +
Getting Started on Linux Systems +
Getting Started on Solaris Systems +

Getting Started on AIX Systems

Begin by running the AFS initialization script to call the +AIX kernel extension facility, which dynamically loads AFS modifications into +the kernel. Then use the SMIT program to configure +partitions for storing AFS volumes, and replace the AIX fsck +program helper with a version that correctly handles AFS volumes. If +the machine is to remain an AFS client machine, incorporate AFS into the AIX +secondary authentication system. + + + + +

Loading AFS into the AIX Kernel

The AIX kernel extension facility is the dynamic kernel +loader provided by IBM Corporation. AIX does not support incorporation +of AFS modifications during a kernel build. +

For AFS to function correctly, the kernel extension facility must run each +time the machine reboots, so the AFS initialization script (included in the +AFS distribution) invokes it automatically. In this section you copy +the script to the conventional location and edit it to select the appropriate +options depending on whether NFS is also to run. +

After editing the script, you run it to incorporate AFS into the +kernel. In later sections you verify that the script correctly +initializes all AFS components, then configure the AIX inittab file +so that the script runs automatically at reboot. +

Mount the AFS CD-ROM for AIX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your AIX documentation. Then change directory as +indicated. +
```
   
+   # cd  /cdrom/rs_aix42/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS kernel library files to the local +/usr/vice/etc/dkload directory, and the AFS initialization script +to the /etc directory. +
```
   
+   # cp -rp  dkload  /usr/vice/etc
+   
+   # cp -p  rc.afs  /etc/rc.afs
+    
+
```
+
Edit the /etc/rc.afs script, setting the NFS +variable as indicated. +
If the machine is not to function as an NFS/AFS Translator, set the +NFS variable as follows. +
```
      
+   NFS=$NFS_NONE
+
```
+
If the machine is to function as an NFS/AFS Translator and is running AIX +4.2.1 or higher, set the NFS variable as +follows. Note that NFS must already be loaded into the kernel, which +happens automatically on systems running AIX 4.1.1 and later, as +long as the file /etc/exports exists. +
```
   
+   NFS=$NFS_IAUTH
+   
+
```
+
Invoke the /etc/rc.afs script to load AFS modifications +into the kernel. You can ignore any error messages about the inability +to start the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/rc.afs
+   
+
```
+

+ + + + +

Configuring Server Partitions on AIX Systems

Every AFS file server machine must have at least one +partition or logical volume dedicated to storing AFS volumes. Each +server partition is mounted at a directory named /vicepxx, +where xx is one or two lowercase letters. The +/vicepxx directories must reside in the file server +machine's root directory, not in one of its subdirectories (for example, +/usr/vicepa is not an acceptable directory location). For +additional information, see Performing Platform-Specific Procedures. +

To configure server partitions on an AIX system, perform the following +procedures: +

Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Use the SMIT program to create a journaling file system on each +partition to be configured as an AFS server partition. +
Mount each partition at one of the /vicepxx +directories. Choose one of the following three methods: +
- Use the SMIT program +
- Use the mount -a command to mount all partitions at once +
- Use the mount command on each partition in turn +
+
Also configure the partitions so that they are mounted automatically at +each reboot. For more information, refer to the AIX +documentation. +

+ + + + +

Replacing the fsck Program Helper on AIX Systems

In this section, you make modifications to guarantee that the +appropriate fsck program runs on AFS server partitions. The +fsck program provided with the operating system must never run on +AFS server partitions. Because it does not recognize the structures +that the File Server uses to organize volume data, it removes all of the +data. To repeat: +

Never run the standard fsck program on AFS server partitions. +It discards AFS volumes. +

On AIX systems, you do not replace the fsck binary itself, but +rather the program helper file included in the AIX distribution as +/sbin/helpers/v3fshelper. +

Move the AIX fsck program helper to a safe location and install +the version from the AFS distribution in its place. The AFS CD-ROM must +still be mounted at the /cdrom directory. +
```
   
+   # cd /sbin/helpers
+   
+   # mv v3fshelper v3fshelper.noafs
+   
+   # cp -p /cdrom/rs_aix42/root.server/etc/v3fshelper v3fshelper
+   
+ 
+
```
+
If you plan to retain client functionality on this machine after +completing the installation, proceed to Enabling AFS Login on AIX Systems. Otherwise, proceed to Starting the BOS Server. +

+ + + + + +

Enabling AFS Login on AIX Systems

Note:

If you plan to remove client functionality from this machine +after completing the installation, skip this section and proceed to Starting the BOS Server. +

Follow the instructions in this section to incorporate AFS modifications +into the AIX secondary authentication system. +

Issue the ls command to verify that the +afs_dynamic_auth and afs_dynamic_kerbauth programs are +installed in the local /usr/vice/etc directory. +
```
   
+   # ls /usr/vice/etc   
+
```
+
If the files do not exist, mount the AFS CD-ROM for AIX (if it is not +already), change directory as indicated, and copy them. +
```
  
+   # cd /cdrom/rs_aix42/root.client/usr/vice/etc
+   
+   # cp  -p  afs_dynamic*  /usr/vice/etc
+   
+
```
+
Edit the local /etc/security/user file, making changes to the +indicated stanzas: +
- In the default stanza, set the registry attribute to +DCE (not to AFS), as follows: +
```
   
+   registry = DCE
+   
+
```
  +
- In the default stanza, set the SYSTEM attribute as +indicated. +
  If the machine is an AFS client only, set the following value: +
```
   
+   SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])"   
+
```
  +
  If the machine is both an AFS and a DCE client, set the following value (it +must appear on a single line in the file): +
```
   
+   SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL]  \
+       AND compat[SUCCESS])"
+   
+
```
  +
- In the root stanza, set the registry attribute as +follows. It enables the local superuser root to log into the +local file system only, based on the password listed in the local password +file. +
```
   
+   root:
+         registry = files
+   
+
```
  +
+
Edit the local /etc/security/login.cfg file, creating or +editing the indicated stanzas: +
- In the DCE stanza, set the program attribute as +follows. +
  If you use the AFS Authentication Server (kaserver +process): +
```
   
+   DCE:
+        program = /usr/vice/etc/afs_dynamic_auth   
+
```
  +
  If you use a Kerberos implementation of AFS authentication: +
```
   
+   DCE:
+        program = /usr/vice/etc/afs_dynamic_kerbauth
+   
+
```
  +
- In the AFS stanza, set the program attribute as +follows. +
  If you use the AFS Authentication Server (kaserver +process): +
```
   
+   AFS:
+        program = /usr/vice/etc/afs_dynamic_auth   
+
```
  +
  If you use a Kerberos implementation of AFS authentication: +
```
   
+   AFS:
+        program = /usr/vice/etc/afs_dynamic_kerbauth
+   
+
```
  +
+
Proceed to Starting the BOS Server (or if referring to these instructions while installing an +additional file server machine, return to Starting Server Programs). +

Getting Started on Digital UNIX Systems

Begin by building AFS modifications into a new static +kernel; Digital UNIX does not support dynamic loading. Then create +partitions for storing AFS volumes, and replace the Digital UNIX +fsck program with a version that correctly handles AFS +volumes. If the machine is to remain an AFS client machine, incorporate +AFS into the machine's Security Integration Architecture (SIA) +matrix. + + + + +

Building AFS into the Digital UNIX Kernel

Use the following instructions to build AFS modifications +into the kernel on a Digital UNIX system. +

Create a copy called AFS of the basic kernel configuration file +included in the Digital UNIX distribution as +/usr/sys/conf/machine_name, where machine_name is +the machine's hostname in all uppercase letters. +
```
   
+   # cd /usr/sys/conf
+   
+   # cp machine_name AFS
+   
+
```
+

Add AFS to the list of options in the configuration file you created in +the previous step, so that the result looks like the following: +

          .                   .
+          .                   .
+       options               UFS
+       options               NFS
+       options               AFS
+          .                   .
+          .                   .
+   
+

Add an entry for AFS to two places in the file +/usr/sys/conf/files. +

Add a line for AFS to the list of OPTIONS, so that the result +looks like the following: +

             .                .      .
+             .                .      .
+      OPTIONS/nfs          optional nfs 
+      OPTIONS/afs          optional afs 
+      OPTIONS/nfs_server   optional nfs_server
+             .                .      .
+             .                .      .
+   
+

Add an entry for AFS to the list of MODULES, so that the result +looks like the following: +

             .                  .        .          .
+             .                  .        .          .
+      #
+      MODULE/nfs_server	    optional nfs_server Binary
+      nfs/nfs_server.c      module nfs_server optimize -g3
+      nfs/nfs3_server.c	    module nfs_server optimize -g3
+      #
+      MODULE/afs            optional afs Binary
+      afs/libafs.c          module afs
+      #
+   
+

Add an entry for AFS to two places in the file +/usr/sys/vfs/vfs_conf.c. +

Add AFS to the list of defined file systems, so that the result looks like +the following: +

        .       .              
+        .       .              
+     #include <afs.h>
+     #if defined(AFS) && AFS
+            extern struct vfsops afs_vfsops;
+     #endif  
+        .       .              
+        .       .              
+   
+

Put a declaration for AFS in the vfssw[] table's +MOUNT_ADDON slot, so that the result looks like the following: +

        .                          .              .
+        .                          .              .
+      &fdfs_vfsops,         "fdfs",   /* 12 = MOUNT_FDFS */
+   #if	defined(AFS)
+      &afs_vfsops,          "afs",
+   #else
+      (struct vfsops *)0,   "",       /* 13 = MOUNT_ADDON */
+   #endif
+   #if NFS && INFS_DYNAMIC   
+       &nfs3_vfsops,        "nfsv3",  /* 14 = MOUNT_NFS3 */		
+   
+

Mount the AFS CD-ROM for Digital UNIX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Digital UNIX documentation. Then change +directory as indicated. +
```
   
+   # cd /cdrom/alpha_dux40/root.client
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /sbin/init.d on Digital +UNIX machines). Note the removal of the .rc extension +as you copy the script. +
```
   
+   # cp usr/vice/etc/afs.rc  /sbin/init.d/afs
+   
+
```
+
Copy the AFS kernel module to the local /usr/sys/BINARY +directory. +
If the machine's kernel supports NFS server functionality: +
```
  
+   # cp bin/libafs.o /usr/sys/BINARY/afs.mod   
+
```
+
If the machine's kernel does not support NFS server +functionality: +
```
  
+   # cp bin/libafs.nonfs.o /usr/sys/BINARY/afs.mod
+   
+
```
+
Configure and build the kernel. Respond to any prompts by pressing +<Return>. The resulting kernel resides in the file +/sys/AFS/vmunix. +
```
   
+   # doconfig -c AFS
+   
+
```
+
Rename the existing kernel file and copy the new, AFS-modified file to the +standard location. +
```
   
+   # mv /vmunix /vmunix_noafs
+   
+   # cp /sys/AFS/vmunix /vmunix
+   
+
```
+

Reboot the machine to start using the new kernel, and login again as the +superuser root. +

   
+   # cd /
+   
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+

+ + + + +

Configuring Server Partitions on Digital UNIX Systems

Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Add a line with the following format to the file systems registry file, +/etc/fstab, for each directory just created. The entry maps +the directory name to the disk partition to be mounted on it. +
```
   
+   /dev/disk /vicepxx ufs rw 0 2
+
```
+
The following is an example for the first partition being +configured. +
```
   
+   /dev/rz3a /vicepa ufs rw 0 2
+   
+
```
+
Create a file system on each partition that is to be mounted at a +/vicepxx directory. The following command is +probably appropriate, but consult the Digital UNIX documentation for more +information. +
```
   
+   # newfs -v /dev/disk
+   
+
```
+
Mount each partition by issuing either the mount -a command to +mount all partitions at once or the mount command to mount each +partition in turn. +

+ + + + +

Replacing the fsck Program on Digital UNIX Systems

Never run the standard fsck program on AFS server partitions. +It discards AFS volumes. +

On Digital UNIX systems, the files /sbin/fsck and +/usr/sbin/fsck are driver programs. Rather than replacing +either of them, you replace the actual binary included in the Digital UNIX +distribution as /sbin/ufs_fsck and +/usr/sbin/ufs_fsck. +

Install the vfsck binary to the /sbin and +/usr/sbin directories. The AFS CD-ROM must still be mounted +at the /cdrom directory. +

   
+   # cd /cdrom/alpha_dux40/root.server/etc
+   
+   # cp vfsck /sbin/vfsck
+   
+   # cp vfsck /usr/sbin/vfsck
+   
+

Rename the Digital UNIX fsck binaries and create symbolic links +to the vfsck program. +

   
+   # cd /sbin
+   
+   # mv ufs_fsck ufs_fsck.noafs
+   
+   # ln -s vfsck ufs_fsck
+   
+   # cd /usr/sbin
+   
+   # mv ufs_fsck ufs_fsck.noafs
+   
+   # ln -s vfsck ufs_fsck
+   
+

If you plan to retain client functionality on this machine after +completing the installation, proceed to Enabling AFS Login on Digital UNIX Systems. Otherwise, proceed to Starting the BOS Server. +

+ + + + + + +

Enabling AFS Login on Digital UNIX Systems

Note:

If you plan to remove client functionality from this machine +after completing the installation, skip this section and proceed to Starting the BOS Server. +

On Digital UNIX systems, the AFS initialization script automatically +incorporates the AFS authentication library file into the Security Integration +Architecture (SIA) matrix on the machine, so that users with AFS accounts +obtain a token at login. In this section you copy the library file to +the appropriate location. +

For more information on SIA, see the Digital UNIX reference page for +matrix.conf, or consult the section on security in your +Digital UNIX documentation. +
Note: If the machine runs both the DCE and AFS client software, AFS must start +after DCE. Consult the AFS initialization script for suggested symbolic +links to create for correct ordering. Also, the system startup script +order must initialize SIA before any long-running process that uses +authentication. +
+

Perform the following steps to enable AFS login. +

Mount the AFS CD-ROM for Digital UNIX on the local /cdrom +directory, if it is not already. Change directory as indicated. +
```
   
+   # cd /cdrom/alpha_dux40/lib/afs
+   
+
```
+
Copy the appropriate AFS authentication library file to the local +/usr/shlib directory. +
If you use the AFS Authentication Server (kaserver process) in +the cell: +
```
   
+   # cp  libafssiad.so  /usr/shlib   
+
```
+
If you use a Kerberos implementation of AFS authentication, rename the +library file as you copy it: +
```
   
+   # cp  libafssiad.krb.so  /usr/shlib/libafssiad.so
+   
+
```
+
Proceed to Starting the BOS Server (or if referring to these instructions while installing an +additional file server machine, return to Starting Server Programs). +

Getting Started on HP-UX Systems

Begin by building AFS modifications into a new kernel; +HP-UX does not support dynamic loading. Then create partitions for +storing AFS volumes, and install and configure the AFS-modified +fsck program to run on AFS server partitions. If the machine +is to remain an AFS client machine, incorporate AFS into the machine's +Pluggable Authentication Module (PAM) scheme. + + + + +

Building AFS into the HP-UX Kernel

Use the following instructions to build AFS modifications +into the kernel on an HP-UX system. +

Move the existing kernel-related files to a safe location. +

   
+   # cp /stand/vmunix /stand/vmunix.noafs
+   
+   # cp /stand/system /stand/system.noafs
+   
+

Mount the AFS CD-ROM for HP-UX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your HP-UX documentation. Then change directory +as indicated. +
```
   
+   # cd /cdrom/hp_ux110/root.client
+   
+
```
+
Copy the AFS initialization file to the local directory for initialization +files (by convention, /sbin/init.d on HP-UX +machines). Note the removal of the .rc extension as +you copy the file. +
```
   
+   # cp usr/vice/etc/afs.rc  /sbin/init.d/afs
+   
+
```
+
Copy the file afs.driver to the local +/usr/conf/master.d directory, changing its name to +afs as you do. +
```
     
+   # cp  usr/vice/etc/afs.driver  /usr/conf/master.d/afs
+   
+
```
+
Copy the AFS kernel module to the local /usr/conf/lib +directory. +
If the machine's kernel supports NFS server functionality: +
```
   
+   # cp bin/libafs.a /usr/conf/lib   
+
```
+
If the machine's kernel does not support NFS server functionality, +change the file's name as you copy it: +
```
   
+   # cp bin/libafs.nonfs.a /usr/conf/lib/libafs.a
+   
+
```
+
Incorporate the AFS driver into the kernel, either using the +SAM program or a series of individual commands. +
- To use the SAM program: +
  1. Invoke the SAM program, specifying the hostname of the local +machine as local_hostname. The SAM graphical user +interface pops up. +
```
   
+   # sam -display local_hostname:0 
+   
+
```
    +
  2. Choose the Kernel Configuration icon, then the +Drivers icon. From the list of drivers, select +afs. +
  3. Open the pull-down Actions menu and choose the Add Driver +to Kernel option. +
  4. Open the Actions menu again and choose the Create a New +Kernel option. +
  5. Confirm your choices by choosing Yes and OK when +prompted by subsequent pop-up windows. The SAM program +builds the kernel and reboots the system. +
  6. Login again as the superuser root. +
```
   
+   login: root
+   Password: root_password
+   
+
```
    +
  +
- To use individual commands: +
  1. Edit the file /stand/system, adding an entry for afs +to the Subsystems section. +
  2. Change to the /stand/build directory and issue the +mk_kernel command to build the kernel. +
```
   
+   # cd /stand/build
+      
+   # mk_kernel
+   
+
```
    +
  3. Move the new kernel to the standard location (/stand/vmunix), +reboot the machine to start using it, and login again as the superuser +root. +
```
   
+   # mv /stand/build/vmunix_test /stand/vmunix
+      
+   # cd /
+      
+   # shutdown -r now		
+   
+   login: root
+   Password: root_password
+   
+
```
    +
  +
+

+ + + + +

Configuring Server Partitions on HP-UX Systems

Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Use the SAM program to create a file system on each +partition. For instructions, consult the HP-UX documentation. +
On some HP-UX systems that use logical volumes, the SAM program +automatically mounts the partitions. If it has not, mount each +partition by issuing either the mount -a command to mount all +partitions at once or the mount command to mount each partition in +turn. +

+ + + + +

Configuring the AFS-modified fsck Program on HP-UX Systems

Never run the standard fsck program on AFS server partitions. +It discards AFS volumes. +

On HP-UX systems, there are several configuration files to install in +addition to the AFS-modified fsck program (the vfsck +binary). +

Create the command configuration file +/sbin/lib/mfsconfig.d/afs. Use a text editor to place +the indicated two lines in it: +
```
   
+   format_revision 1
+   fsck            0        m,P,p,d,f,b:c:y,n,Y,N,q,
+   
+
```
+
Create and change directory to an AFS-specific command directory called +/sbin/fs/afs. +
```
   
+   # mkdir /sbin/fs/afs
+   
+   # cd  /sbin/fs/afs
+   
+
```
+
Copy the AFS-modified version of the fsck program (the +vfsck binary) and related files from the distribution directory to +the new AFS-specific command directory. +
```
   
+   # cp -p /cdrom/hp_ux110/root.server/etc/*  .
+          
+
```
+
Change the vfsck binary's name to fsck and set +the mode bits appropriately on all of the files in the /sbin/fs/afs +directory. +
```
      
+   # mv  vfsck  fsck
+   
+   # chmod  755  *
+   
+
```
+

Edit the /etc/fstab file, changing the file system type for +each AFS server partition from hfs to afs. This +ensures that the AFS-modified fsck program runs on the appropriate +partitions. +

The sixth line in the following example of an edited file shows an AFS +server partition, /vicepa. +

   
+   /dev/vg00/lvol1 / hfs defaults 0 1
+   /dev/vg00/lvol4 /opt hfs defaults 0 2
+   /dev/vg00/lvol5 /tmp hfs defaults 0 2
+   /dev/vg00/lvol6 /usr hfs defaults 0 2
+   /dev/vg00/lvol8 /var hfs defaults 0 2
+   /dev/vg00/lvol9 /vicepa afs defaults 0 2
+   /dev/vg00/lvol7 /usr/vice/cache hfs defaults 0 2
+   
+

If you plan to retain client functionality on this machine after +completing the installation, proceed to Enabling AFS Login on HP-UX Systems. Otherwise, proceed to Starting the BOS Server. +

+ + + + + + +

Enabling AFS Login on HP-UX Systems

Note:

If you plan to remove client functionality from this machine +after completing the installation, skip this section and proceed to Starting the BOS Server. +

At this point you incorporate AFS into the operating system's +Pluggable Authentication Module (PAM) scheme. PAM integrates all +authentication mechanisms on the machine, including login, to provide the +security infrastructure for authenticated access to and from the +machine. +

Explaining PAM is beyond the scope of this document. It is assumed +that you understand the syntax and meanings of settings in the PAM +configuration file (for example, how the other entry works, the +effect of marking an entry as required, optional, or +sufficient, and so on). +

The following instructions explain how to alter the entries in the PAM +configuration file for each service for which you wish to use AFS +authentication. Other configurations possibly also work, but the +instructions specify the recommended and tested configuration. +
Note: The instructions specify that you mark each entry as +optional. However, marking some modules as optional can mean +that they grant access to the corresponding service even when the user does +not meet all of the module's requirements. In some operating +system revisions, for example, if you mark as optional the module that +controls login via a dial-up connection, it allows users to login without +providing a password. See the IBM AFS Release Notes for a +discussion of any limitations that apply to this operating system. +
Also, with some operating system versions you must install patches for PAM +to interact correctly with certain authentication programs. For +details, see the IBM AFS Release Notes. +
+

The recommended AFS-related entries in the PAM configuration file make use +of one or more of the following three attributes. +

try_first_pass +: This is a standard PAM attribute that can be included on entries after the +first one for a service; it directs the module to use the password that +was provided to the first module. For the AFS module, it means that AFS +authentication succeeds if the password provided to the module listed first is +the user's correct AFS password. For further discussion of this +attribute and its alternatives, see the operating system's PAM +documentation. +
ignore_root +: This attribute, specific to the AFS PAM module, directs it to ignore not +only the local superuser root, but also any user with UID 0 +(zero). +
setenv_password_expires +: This attribute, specific to the AFS PAM module, sets the environment +variable PASSWORD_EXPIRES to the expiration date of the user's AFS +password, which is recorded in the Authentication Database. +

Perform the following steps to enable AFS login. +

Mount the AFS CD-ROM for HP-UX on the /cdrom directory, if it +is not already. Then change directory as indicated. +
```
  
+   # cd /usr/lib/security
+   
+
```
+
Copy the AFS authentication library file to the +/usr/lib/security directory. Then create a symbolic link to +it whose name does not mention the version. Omitting the version +eliminates the need to edit the PAM configuration file if you later update the +library file. +
If you use the AFS Authentication Server (kaserver process) in +the cell: +
```
   
+   # cp /cdrom/hp_ux110/lib/pam_afs.so.1  .
+  
+   # ln -s  pam_afs.so.1  pam_afs.so   
+
```
+
If you use a Kerberos implementation of AFS authentication: +
```
  
+   # cp /cdrom/hp_ux110/lib/pam_afs.krb.so.1   .
+  
+   # ln -s pam_afs.krb.so.1 pam_afs.so
+   
+
```
+
Edit the Authentication management section of the HP-UX PAM +configuration file, /etc/pam.conf by convention. The +entries in this section have the value auth in their second +field. +
First edit the standard entries, which refer to the HP-UX PAM module +(usually, the file /usr/lib/security/libpam_unix.1) in their +fourth field. For each service for which you want to use AFS +authentication, edit the third field of its entry to read +optional. The pam.conf file in the HP-UX +distribution usually includes standard entries for the login and +ftp services, for instance. +
If there are services for which you want to use AFS authentication, but for +which the pam.conf file does not already include a standard +entry, you must create that entry and place the value optional in +its third field. For instance, the HP-UX pam.conf +file does not usually include standard entries for the remsh or +telnet services. +
Then create an AFS-related entry for each service, placing it immediately +below the standard entry. The following example shows what the +Authentication Management section looks like after you have you +edited or created entries for the services mentioned previously. Note +that the example AFS entries appear on two lines only for legibility. +
```
   
+   login   auth  optional  /usr/lib/security/libpam_unix.1
+   login   auth  optional  /usr/lib/security/pam_afs.so      \
+         try_first_pass  ignore_root  setenv_password_expires
+   ftp     auth  optional  /usr/lib/security/libpam_unix.1
+   ftp     auth  optional  /usr/lib/security/pam_afs.so      \
+         try_first_pass  ignore_root
+   remsh   auth  optional  /usr/lib/security/libpam_unix.1
+   remsh   auth  optional  /usr/lib/security/pam_afs.so      \
+         try_first_pass  ignore_root		
+   telnet  auth  optional  /usr/lib/security/libpam_unix.1
+   telnet  auth  optional  /usr/lib/security/pam_afs.so      \
+         try_first_pass  ignore_root  setenv_password_expires
+   
+
```
+

If you use the Common Desktop Environment (CDE) on the machine and want +users to obtain an AFS token as they log in, also add or edit the following +four entries in the Authentication management section. Note +that the AFS-related entries appear on two lines here only for +legibility. +

  
+   dtlogin   auth  optional  /usr/lib/security/libpam_unix.1
+   dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
+         try_first_pass  ignore_root
+   dtaction  auth  optional  /usr/lib/security/libpam_unix.1
+   dtaction  auth  optional  /usr/lib/security/pam_afs.so     \
+         try_first_pass  ignore_root
+   
+

Proceed to Starting the BOS Server (or if referring to these instructions while installing an +additional file server machine, return to Starting Server Programs). +

Getting Started on IRIX Systems

+ + + + + + + +

To incorporate AFS into the kernel on IRIX systems, choose one of two +methods: +

Run the AFS initialization script to invoke the ml program +distributed by Silicon Graphics, Incorporated (SGI), which dynamically loads +AFS modifications into the kernel +
Build a new static kernel +

Then create partitions for storing AFS volumes. You do not need to +replace the IRIX fsck program because SGI has already modified it +to handle AFS volumes properly. If the machine is to remain an AFS +client machine, verify that the IRIX login utility installed on the machine +grants an AFS token. +

In preparation for either dynamic loading or kernel building, perform the +following procedures: +

Mount the AFS CD-ROM for IRIX on the /cdrom directory. +For instructions on mounting CD-ROMs (either locally or remotely via NFS), see +your IRIX documentation. Then change directory as indicated. +
```
   
+   # cd  /cdrom/sgi_65/root.client
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/init.d on IRIX +machines). Note the removal of the .rc extension as +you copy the script. +
```
   
+   # cp -p   usr/vice/etc/afs.rc  /etc/init.d/afs
+   
+
```
+
Issue the uname -m command to determine the machine's CPU +board type. The IPxx value in the output must match +one of the supported CPU board types listed in the IBM AFS Release +Notes for the current version of AFS. +
```
   
+   # uname -m
+    
+
```
+
Proceed to either Loading AFS into the IRIX Kernel or Building AFS into the IRIX Kernel. +

+ + + + + + + +

Loading AFS into the IRIX Kernel

The ml program is the dynamic kernel loader +provided by SGI for IRIX systems. If you use it rather than building +AFS modifications into a static kernel, then for AFS to function correctly the +ml program must run each time the machine reboots. +Therefore, the AFS initialization script (included on the AFS CD-ROM) invokes +it automatically when the afsml configuration variable is +activated. In this section you activate the variable and run the +script. +

In later sections you verify that the script correctly initializes all AFS +components, then create the links that incorporate AFS into the IRIX startup +and shutdown sequence. +

Create the local /usr/vice/etc/sgiload directory to house the +AFS kernel library file. +
```
   
+   # mkdir /usr/vice/etc/sgiload
+   
+
```
+
Copy the appropriate AFS kernel library file to the +/usr/vice/etc/sgiload directory. The +IPxx portion of the library file name must match the value +previously returned by the uname -m command. Also choose the +file appropriate to whether the machine's kernel supports NFS server +functionality (NFS must be supported for the machine to act as an NFS/AFS +Translator). Single- and multiprocessor machines use the same library +file. +
(You can choose to copy all of the kernel library files into the +/usr/vice/etc/sgiload directory, but they require a significant amount +of space.) +
If the machine's kernel supports NFS server functionality: +
```
   
+   # cp -p  usr/vice/etc/sgiload/libafs.IPxx.o  /usr/vice/etc/sgiload   
+
```
+
If the machine's kernel does not support NFS server +functionality: +
```
   
+   # cp -p  usr/vice/etc/sgiload/libafs.IPxx.nonfs.o   \
+                   /usr/vice/etc/sgiload
+   
+
```
+
Issue the chkconfig command to activate the afsml +configuration variable. +
```
   
+   # /etc/chkconfig -f afsml on   
+
```
+
If the machine is to function as an NFS/AFS Translator and the kernel +supports NFS server functionality, activate the afsxnfs +variable. +
```
   
+   # /etc/chkconfig -f afsxnfs on
+   
+
```
+
Run the /etc/init.d/afs script to load AFS extensions +into the kernel. The script invokes the ml command, +automatically determining which kernel library file to use based on this +machine's CPU type and the activation state of the afsxnfs +variable. +
You can ignore any error messages about the inability to start the BOS +Server or the Cache Manager or AFS client. +
```
   
+   # /etc/init.d/afs start
+   
+
```
+
Proceed to Configuring Server Partitions on IRIX Systems. +

+ +

Building AFS into the IRIX Kernel

Use the following instructions to build AFS modifications +into the kernel on an IRIX system. +

Copy the kernel initialization file afs.sm to the local +/var/sysgen/system directory, and the kernel master file +afs to the local /var/sysgen/master.d +directory. +
```
   
+   # cp -p  bin/afs.sm  /var/sysgen/system
+   
+   # cp -p  bin/afs  /var/sysgen/master.d
+   
+
```
+
Copy the appropriate AFS kernel library file to the local file +/var/sysgen/boot/afs.a; the IPxx +portion of the library file name must match the value previously returned by +the uname -m command. Also choose the file appropriate to +whether the machine's kernel supports NFS server functionality (NFS must +be supported for the machine to act as an NFS/AFS Translator). Single- +and multiprocessor machines use the same library file. +
If the machine's kernel supports NFS server functionality: +
```
   
+   # cp -p   bin/libafs.IPxx.a   /var/sysgen/boot/afs.a   
+
```
+
If the machine's kernel does not support NFS server +functionality: +
```
   
+   # cp -p  bin/libafs.IPxx.nonfs.a  /var/sysgen/boot/afs.a
+   
+
```
+
Issue the chkconfig command to deactivate the afsml +configuration variable. +
```
   
+   # /etc/chkconfig -f afsml off   
+
```
+
If the machine is to function as an NFS/AFS Translator and the kernel +supports NFS server functionality, activate the afsxnfs +variable. +
```
    
+   # /etc/chkconfig -f afsxnfs on
+   
+
```
+
Copy the existing kernel file, /unix, to a safe +location. Compile the new kernel, which is created in the file +/unix.install. It overwrites the existing +/unix file when the machine reboots in the next step. +
```
   
+   # cp /unix /unix_noafs
+   
+   # autoconfig
+   
+
```
+

Reboot the machine to start using the new kernel, and login again as the +superuser root. +

   
+   # cd /
+         
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+

+ + + + +

Configuring Server Partitions on IRIX Systems

AFS supports use of both EFS and XFS partitions for housing AFS +volumes. SGI encourages use of XFS partitions. +

Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Add a line with the following format to the file systems registry file, +/etc/fstab, for each partition (or logical volume created with the +XLV volume manager) to be mounted on one of the directories created in the +previous step. +
For an XFS partition or logical volume: +
```
   
+   /dev/dsk/disk  /vicepxx  xfs  rw,raw=/dev/rdsk/disk  0  0   
+
```
+
For an EFS partition: +
```
   
+   /dev/dsk/disk  /vicepxx  efs  rw,raw=/dev/rdsk/disk  0  0   
+
```
+
The following are examples of an entry for each file system type: +
```
   
+   /dev/dsk/dks0d2s6 /vicepa  xfs rw,raw=/dev/rdsk/dks0d2s6  0 0
+   /dev/dsk/dks0d3s1 /vicepb  efs rw,raw=/dev/rdsk/dks0d3s1  0 0
+   
+
```
+
Create a file system on each partition that is to be mounted on a +/vicepxx directory. The following commands are +probably appropriate, but consult the IRIX documentation for more +information. In both cases, raw_device is a raw device name +like /dev/rdsk/dks0d0s0 for a single disk partition or +/dev/rxlv/xlv0 for a logical volume. +
For XFS file systems, include the indicated options to configure the +partition or logical volume with inodes large enough to accommodate +AFS-specific information: +
```
   
+   # mkfs -t xfs -i size=512 -l size=4000b raw_device   
+
```
+
For EFS file systems: +
```
   
+   # mkfs -t efs raw_device
+   
+
```
+
Mount each partition by issuing either the mount -a command to +mount all partitions at once or the mount command to mount each +partition in turn. +
(Optional) If you have configured partitions or logical volumes +to use XFS, issue the following command to verify that the inodes are +configured properly (are large enough to accommodate AFS-specific +information). If the configuration is correct, the command returns no +output. Otherwise, it specifies the command to run in order to +configure each partition or logical volume properly. +
```
   
+   # /usr/afs/bin/xfs_size_check
+   
+
```
+
If you plan to retain client functionality on this machine after +completing the installation, proceed to Enabling AFS Login on IRIX Systems. Otherwise, proceed to Starting the BOS Server. +

+ + + + +

Enabling AFS Login on IRIX Systems

Note:

If you plan to remove client functionality from this machine +after completing the installation, skip this section and proceed to Starting the BOS Server. +

The standard IRIX command-line login program and the graphical +xdm login program both automatically grant an AFS token when AFS is +incorporated into the machine's kernel. However, some IRIX +distributions use another login utility by default, and it does not +necessarily incorporate the required AFS modifications. If that is the +case, you must disable the default utility if you want AFS users to obtain AFS +tokens at login. For further discussion, see the IBM AFS Release +Notes. +

If you configure the machine to use an AFS-modified login utility, then the +afsauthlib.so and afskauthlib.so files +(included in the AFS distribution) must reside in the /usr/vice/etc +directory. Issue the ls command to verify. +

  
+   # ls /usr/vice/etc   
+

If the files do not exist, mount the AFS CD-ROM for IRIX (if it is not +already), change directory as indicated, and copy them. +

  
+   # cd /cdrom/sgi_65/root.client/usr/vice/etc
+   
+   # cp  -p  *authlib*  /usr/vice/etc   
+

After taking any necessary action, proceed to Starting the BOS Server. +

Getting Started on Linux Systems

+ + + + +

Begin by running the AFS initialization script to call the +insmod program, which dynamically loads AFS modifications into the +kernel. Then create partitions for storing AFS volumes. You do +not need to replace the Linux fsck program. If the machine +is to remain an AFS client machine, incorporate AFS into the machine's +Pluggable Authentication Module (PAM) scheme. + + + + +

Loading AFS into the Linux Kernel

The insmod program is the dynamic kernel loader +for Linux. Linux does not support incorporation of AFS modifications +during a kernel build. +

For AFS to function correctly, the insmod program must run each +time the machine reboots, so the AFS initialization script (included on the +AFS CD-ROM) invokes it automatically. The script also includes commands +that select the appropriate AFS library file automatically. In this +section you run the script. +

In later sections you verify that the script correctly initializes all AFS +components, then activate a configuration variable, which results in the +script being incorporated into the Linux startup and shutdown sequence. +

Mount the AFS CD-ROM for Linux on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Linux documentation. Then change directory +as indicated. +
```
   
+   # cd  /cdrom/i386_linux22/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS kernel library files to the local +/usr/vice/etc/modload directory. The filenames for the +libraries have the format +libafs-version.o, where version +indicates the kernel build level. The string .mp in +the version indicates that the file is appropriate for machines +running a multiprocessor kernel. +
```
   
+   # cp -rp  modload  /usr/vice/etc
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/rc.d/init.d +on Linux machines). Note the removal of the .rc +extension as you copy the script. +
```
   
+   # cp -p   afs.rc  /etc/rc.d/init.d/afs 
+    
+
```
+
Run the AFS initialization script to load AFS extensions into the +kernel. You can ignore any error messages about the inability to start +the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/rc.d/init.d/afs  start
+   
+
```
+

+ + + + +

Configuring Server Partitions on Linux Systems

Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Add a line with the following format to the file systems registry file, +/etc/fstab, for each directory just created. The entry maps +the directory name to the disk partition to be mounted on it. +
```
   
+   /dev/disk  /vicepxx  ext2  defaults  0  2   
+
```
+
The following is an example for the first partition being +configured. +
```
   
+   /dev/sda8 /vicepa ext2 defaults 0 2
+   
+
```
+
Create a file system on each partition that is to be mounted at a +/vicepxx directory. The following command is +probably appropriate, but consult the Linux documentation for more +information. +
```
   
+   # mkfs -v /dev/disk
+   
+
```
+
Mount each partition by issuing either the mount -a command to +mount all partitions at once or the mount command to mount each +partition in turn. +
If you plan to retain client functionality on this machine after +completing the installation, proceed to Enabling AFS Login on Linux Systems. Otherwise, proceed to Starting the BOS Server. +

+ + + + + +

Enabling AFS Login on Linux Systems

Note:

If you plan to remove client functionality from this machine +after completing the installation, skip this section and proceed to Starting the BOS Server. +

The recommended AFS-related entries in the PAM configuration file make use +of one or more of the following three attributes. +

try_first_pass +: This is a standard PAM attribute that can be included on entries after the +first one for a service; it directs the module to use the password that +was provided to the first module. For the AFS module, it means that AFS +authentication succeeds if the password provided to the module listed first is +the user's correct AFS password. For further discussion of this +attribute and its alternatives, see the operating system's PAM +documentation. +
ignore_root +: This attribute, specific to the AFS PAM module, directs it to ignore not +only the local superuser root, but also any user with UID 0 +(zero). +
setenv_password_expires +: This attribute, specific to the AFS PAM module, sets the environment +variable PASSWORD_EXPIRES to the expiration date of the user's AFS +password, which is recorded in the Authentication Database. +

Perform the following steps to enable AFS login. +

Mount the AFS CD-ROM for Linux on the /cdrom directory, if it +is not already. Then change to the directory for PAM modules, which +depends on which Linux distribution you are using. +
If you are using a Linux distribution from Red Hat Software: +
```
   
+   # cd /lib/security   
+
```
+
If you are using another Linux distribution: +
```
   
+   # cd /usr/lib/security
+   
+
```
+
Copy the appropriate AFS authentication library file to the directory to +which you changed in the previous step. Create a symbolic link whose +name does not mention the version. Omitting the version eliminates the +need to edit the PAM configuration file if you later update the library +file. +
If you use the AFS Authentication Server (kaserver +process): +
```
   
+   # cp /cdrom/i386_linux22/lib/pam_afs.so.1  .
+   
+   # ln -s pam_afs.so.1 pam_afs.so   
+
```
+
If you use a Kerberos implementation of AFS authentication: +
```
   
+   # cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1   .
+   
+   # ln -s pam_afs.krb.so.1 pam_afs.so
+   
+
```
+
For each service with which you want to use AFS authentication, insert an +entry for the AFS PAM module into the auth section of the +service's PAM configuration file. (Linux uses a separate +configuration file for each service, unlike some other operating systems which +list all services in a single file.) Mark the entry as +sufficient in the second field. +
Place the AFS entry below any entries that impose conditions under which +you want the service to fail for a user who does not meet the entry's +requirements. Mark these entries required. Place the +AFS entry above any entries that need to execute only if AFS authentication +fails. +
Insert the following AFS entry if using the Red Hat distribution: +
```
   
+   auth  sufficient  /lib/security/pam_afs.so   try_first_pass  ignore_root   
+
```
+
Insert the following AFS entry if using another distribution: +
```
   
+   auth  sufficient  /usr/lib/security/pam_afs.so  try_first_pass  ignore_root   
+
```
+
The following example illustrates the recommended configuration of the +configuration file for the login service +(/etc/pam.d/login) on a machine using the Red Hat +distribution. +
```
   
+   #%PAM-1.0
+   auth      required   /lib/security/pam_securetty.so
+   auth      required   /lib/security/pam_nologin.so
+   auth      sufficient /lib/security/pam_afs.so try_first_pass ignore_root
+   auth      required   /lib/security/pam_pwdb.so shadow nullok
+   account   required   /lib/security/pam_pwdb.so
+   password  required   /lib/security/pam_cracklib.so
+   password  required   /lib/security/pam_pwdb.so shadow nullok use_authtok
+   session   required   /lib/security/pam_pwdb.so
+   
+
```
+
Proceed to Starting the BOS Server (or if referring to these instructions while installing an +additional file server machine, return to Starting Server Programs). +

Getting Started on Solaris Systems

Begin by running the AFS initialization script to call the +modload program distributed by Sun Microsystems, which dynamically +loads AFS modifications into the kernel. Then create partitions for +storing AFS volumes, and install and configure the AFS-modified +fsck program to run on AFS server partitions. If the machine +is to remain an AFS client machine, incorporate AFS into the machine's +Pluggable Authentication Module (PAM) scheme. + + + + +

Loading AFS into the Solaris Kernel

The modload program is the dynamic kernel loader +provided by Sun Microsystems for Solaris systems. Solaris does not +support incorporation of AFS modifications during a kernel build. +

For AFS to function correctly, the modload program must run each +time the machine reboots, so the AFS initialization script (included on the +AFS CD-ROM) invokes it automatically. In this section you copy the +appropriate AFS library file to the location where the modload +program accesses it and then run the script. +

In later sections you verify that the script correctly initializes all AFS +components, then create the links that incorporate AFS into the Solaris +startup and shutdown sequence. +

Mount the AFS CD-ROM for Solaris on the /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Solaris documentation. Then change +directory as indicated. +
```
   
+   # cd  /cdrom/sun4x_56/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/init.d on Solaris +machines). Note the removal of the .rc extension as +you copy the script. +
```
   
+   # cp -p  afs.rc  /etc/init.d/afs
+   
+
```
+
Copy the appropriate AFS kernel library file to the local file +/kernel/fs/afs. +
If the machine is running Solaris 2.6 or the 32-bit version of +Solaris 7, its kernel supports NFS server functionality, and the +nfsd process is running: +
```
   
+   # cp -p modload/libafs.o /kernel/fs/afs   
+
```
+
If the machine is running Solaris 2.6 or the 32-bit version of +Solaris 7, and its kernel does not support NFS server functionality or the +nfsd process is not running: +
```
   
+   # cp -p modload/libafs.nonfs.o /kernel/fs/afs   
+
```
+
If the machine is running the 64-bit version of Solaris 7, its kernel +supports NFS server functionality, and the nfsd process is +running: +
```
   
+   # cp -p modload/libafs64.o /kernel/fs/sparcv9/afs   
+
```
+
If the machine is running the 64-bit version of Solaris 7, and its +kernel does not support NFS server functionality or the nfsd +process is not running: +
```
   
+   # cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs
+   
+
```
+
Run the AFS initialization script to load AFS modifications into the +kernel. You can ignore any error messages about the inability to start +the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/init.d/afs start   
+
```
+
When an entry called afs does not already exist in the local +/etc/name_to_sysnum file, the script automatically creates it and +reboots the machine to start using the new version of the file. If this +happens, log in again as the superuser root after the reboot and +run the initialization script again. This time the required entry +exists in the /etc/name_to_sysnum file, and the modload +program runs. +
```
   
+   login: root
+   Password: root_password
+   
+   # /etc/init.d/afs start
+   
+
```
+

+ + + + +

Configuring the AFS-modified fsck Program on Solaris Systems

Never run the standard fsck program on AFS server partitions. +It discards AFS volumes. +

Create the /usr/lib/fs/afs directory to house the AFS-modified +fsck program and related files. +
```
  
+   # mkdir /usr/lib/fs/afs
+   
+   # cd /usr/lib/fs/afs	
+  
+
```
+
Copy the vfsck binary to the newly created directory, changing +the name as you do so. +
```
   
+   # cp  /cdrom/sun4x_56/root.server/etc/vfsck  fsck
+  
+
```
+

Working in the /usr/lib/fs/afs directory, create the following +links to Solaris libraries: +

  
+   # ln -s /usr/lib/fs/ufs/clri	
+   # ln -s /usr/lib/fs/ufs/df
+   # ln -s /usr/lib/fs/ufs/edquota
+   # ln -s /usr/lib/fs/ufs/ff
+   # ln -s /usr/lib/fs/ufs/fsdb	
+   # ln -s /usr/lib/fs/ufs/fsirand
+   # ln -s /usr/lib/fs/ufs/fstyp
+   # ln -s /usr/lib/fs/ufs/labelit
+   # ln -s /usr/lib/fs/ufs/lockfs
+   # ln -s /usr/lib/fs/ufs/mkfs	
+   # ln -s /usr/lib/fs/ufs/mount
+   # ln -s /usr/lib/fs/ufs/ncheck
+   # ln -s /usr/lib/fs/ufs/newfs
+   # ln -s /usr/lib/fs/ufs/quot
+   # ln -s /usr/lib/fs/ufs/quota
+   # ln -s /usr/lib/fs/ufs/quotaoff
+   # ln -s /usr/lib/fs/ufs/quotaon
+   # ln -s /usr/lib/fs/ufs/repquota
+   # ln -s /usr/lib/fs/ufs/tunefs
+   # ln -s /usr/lib/fs/ufs/ufsdump
+   # ln -s /usr/lib/fs/ufs/ufsrestore
+   # ln -s /usr/lib/fs/ufs/volcopy
+   
+

Append the following line to the end of the file +/etc/dfs/fstypes. +
```
  
+   afs AFS Utilities
+  
+
```
+

Edit the /sbin/mountall file, making two changes. +

Add an entry for AFS to the case statement for option 2, so +that it reads as follows: +

  
+   case "$2" in
+   ufs)    foptions="-o p"
+           ;;
+   afs)    foptions="-o p"
+           ;;
+   s5)     foptions="-y -t /var/tmp/tmp$$ -D"
+           ;;
+   *)      foptions="-y"
+           ;;
+  
+

Edit the file so that all AFS and UFS partitions are checked in +parallel. Replace the following section of code: +

  
+   # For  fsck purposes, we make a distinction between ufs and
+   # other file systems
+   #
+   if [ "$fstype" = "ufs" ]; then
+        ufs_fscklist="$ufs_fscklist $fsckdev"
+        saveentry $fstype "$OPTIONS" $special $mountp
+        continue
+   fi  
+

with the following section of code: +

  
+   # For fsck purposes, we make a distinction between ufs/afs
+   # and other file systems.
+   #
+   if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
+        ufs_fscklist="$ufs_fscklist $fsckdev"
+        saveentry $fstype "$OPTIONS" $special $mountp
+        continue
+   fi
+  
+

+ + + + +

Configuring Server Partitions on Solaris Systems

Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Add a line with the following format to the file systems registry file, +/etc/vfstab, for each partition to be mounted on a directory +created in the previous step. Note the value afs in the +fourth field, which tells Solaris to use the AFS-modified fsck +program on this partition. +
```
   
+   /dev/dsk/disk   /dev/rdsk/disk   /vicepxx   afs   boot_order  yes  
+
```
+
The following is an example for the first partition being +configured. +
```
  
+   /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
+  
+
```
+
Create a file system on each partition that is to be mounted at a +/vicepxx directory. The following command is +probably appropriate, but consult the Solaris documentation for more +information. +
```
  
+   # newfs -v /dev/rdsk/disk
+  
+
```
+
Issue the mountall command to mount all partitions at +once. +
If you plan to retain client functionality on this machine after +completing the installation, proceed to Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems. Otherwise, proceed to Starting the BOS Server. +

+ + + + + + + + +

Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems

Note:

If you plan to remove client functionality from this machine +after completing the installation, skip this section and proceed to Starting the BOS Server. +

The recommended AFS-related entries in the PAM configuration file make use +of one or more of the following three attributes. +

try_first_pass +: This is a standard PAM attribute that can be included on entries after the +first one for a service; it directs the module to use the password that +was provided to the first module. For the AFS module, it means that AFS +authentication succeeds if the password provided to the module listed first is +the user's correct AFS password. For further discussion of this +attribute and its alternatives, see the operating system's PAM +documentation. +
ignore_root +: This attribute, specific to the AFS PAM module, directs it to ignore not +only the local superuser root, but also any user with UID 0 +(zero). +
setenv_password_expires +: This attribute, specific to the AFS PAM module, sets the environment +variable PASSWORD_EXPIRES to the expiration date of the user's AFS +password, which is recorded in the Authentication Database. +

Perform the following steps to enable AFS login. +

Mount the AFS CD-ROM for Solaris on the /cdrom directory, if it +is not already. Then change directory as indicated. +
```
  
+   # cd /usr/lib/security
+   
+
```
+
Copy the AFS authentication library file to the +/usr/lib/security directory. Then create a symbolic link to +it whose name does not mention the version. Omitting the version +eliminates the need to edit the PAM configuration file if you later update the +library file. +
If you use the AFS Authentication Server (kaserver +process): +
```
  
+   # cp /cdrom/sun4x_56/lib/pam_afs.so.1 .
+  
+   # ln -s pam_afs.so.1 pam_afs.so   
+
```
+
If you use a Kerberos implementation of AFS authentication: +
```
     
+   # cp /cdrom/sun4x_56/lib/pam_afs.krb.so.1 .
+  
+   # ln -s pam_afs.krb.so.1 pam_afs.so
+   
+
```
+
Edit the Authentication management section of the Solaris PAM +configuration file, /etc/pam.conf by convention. The +entries in this section have the value auth in their second +field. +
First edit the standard entries, which refer to the Solaris PAM module +(usually, the file /usr/lib/security/pam_unix.so.1) +in their fourth field. For each service for which you want to use AFS +authentication, edit the third field of its entry to read +optional. The pam.conf file in the Solaris +distribution usually includes standard entries for the login, +rlogin, and rsh services, for instance. +
If there are services for which you want to use AFS authentication, but for +which the pam.conf file does not already include a standard +entry, you must create that entry and place the value optional in +its third field. For instance, the Solaris pam.conf +file does not usually include standard entries for the ftp or +telnet services. +
Then create an AFS-related entry for each service, placing it immediately +below the standard entry. The following example shows what the +Authentication Management section looks like after you have you +edited or created entries for the services mentioned previously. Note +that the example AFS entries appear on two lines only for legibility. +
```
  
+   login   auth  optional  /usr/lib/security/pam_unix.so.1
+   login   auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root  setenv_password_expires
+   rlogin  auth  optional  /usr/lib/security/pam_unix.so.1
+   rlogin  auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root  setenv_password_expires
+   rsh     auth  optional  /usr/lib/security/pam_unix.so.1
+   rsh     auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root		
+   ftp     auth  optional  /usr/lib/security/pam_unix.so.1
+   ftp     auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root
+   telnet  auth  optional  /usr/lib/security/pam_unix.so.1
+   telnet  auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root  setenv_password_expires
+   
+
```
+

   
+   dtlogin   auth  optional  /usr/lib/security/pam_unix.so.1
+   dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
+         try_first_pass  ignore_root
+   dtsession  auth  optional /usr/lib/security/pam_unix.so.1
+   dtsession  auth  optional /usr/lib/security/pam_afs.so     \
+         try_first_pass  ignore_root
+   
+

Some Solaris distributions include a script that locates and removes +unneeded files from various file systems. Its conventional location is +/usr/lib/fs/nfs/nfsfind. The script generally uses an +argument to the find command to define which file systems to +search. In this step you modify the command to exclude the +/afs directory. Otherwise, the command traverses the AFS +filespace of every cell that is accessible from the machine, which can take +many hours. The following alterations are possibilities, but you must +verify that they are appropriate for your cell. +
The first possible alteration is to add the -local flag to the +existing command, so that it looks like the following: +
```
  
+   find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;   
+
```
+
Another alternative is to exclude any directories whose names begin with +the lowercase letter a or a non-alphabetic character. +
```
  
+   find /[A-Zb-z]*  remainder of existing command   
+
```
+
Do not use the following command, which still searches under the +/afs directory, looking for a subdirectory of type +4.2. +
```
  
+   find / -fstype 4.2     /* do not use */
+   
+
```
+
Proceed to Starting the BOS Server (or if referring to these instructions while installing an +additional file server machine, return to Starting Server Programs). +

+ + + + + + + +

Starting the BOS Server

You are now ready to start the AFS server processes on this +machine. Begin by copying the AFS server binaries from the CD-ROM to +the conventional local disk location, the /usr/afs/bin +directory. The following instructions also create files in other +subdirectories of the /usr/afs directory. +

Then issue the bosserver command to initialize the Basic +OverSeer (BOS) Server, which monitors and controls other AFS server processes +on its server machine. Include the -noauth flag to disable +authorization checking. Because you have not yet configured your +cell's AFS authentication and authorization mechanisms, the BOS Server +cannot perform authorization checking as it does during normal +operation. In no-authorization mode, it does not verify the identity or +privilege of the issuer of a bos command, and so performs any +operation for anyone. +

Disabling authorization checking gravely compromises cell security. +You must complete all subsequent steps in one uninterrupted pass and must not +leave the machine unattended until you restart the BOS Server with +authorization checking enabled, in Verifying the AFS Initialization Script. +

As it initializes for the first time, the BOS Server creates the following +directories and files, setting the owner to the local superuser +root and the mode bits to limit the ability to write (and in some +cases, read) them. For a description of the contents and function of +these directories and files, see the chapter in the IBM AFS +Administration Guide about administering server machines. For +further discussion of the mode bit settings, see Protecting Sensitive AFS Directories. + + + + + + + + + + + +

/usr/afs/db +
/usr/afs/etc/CellServDB +
/usr/afs/etc/ThisCell +
/usr/afs/local +
/usr/afs/logs +

The BOS Server also creates symbolic links called +/usr/vice/etc/ThisCell and /usr/vice/etc/CellServDB to +the corresponding files in the /usr/afs/etc directory. The +AFS command interpreters consult the CellServDB and +ThisCell files in the /usr/vice/etc directory because +they generally run on client machines. On machines that are AFS servers +only (as this machine currently is), the files reside only in the +/usr/afs/etc directory; the links enable the command +interpreters to retrieve the information they need. Later instructions +for installing the client functionality replace the links with actual +files. +

On the local /cdrom directory, mount the AFS CD-ROM for this +machine's system type, if it is not already. For instructions on +mounting CD-ROMs (either locally or remotely via NFS), consult the operating +system documentation. +

Copy files from the CD-ROM to the local /usr/afs +directory. +

   
+   # cd /cdrom/sysname/root.server/usr/afs
+   
+   # cp -rp  *  /usr/afs
+   
+

+ + +

Issue the bosserver command. Include the +-noauth flag to disable authorization checking. +
```
   
+   # /usr/afs/bin/bosserver -noauth &
+   
+
```
+
Verify that the BOS Server created /usr/vice/etc/ThisCell and +/usr/vice/etc/CellServDB as symbolic links to the corresponding +files in the /usr/afs/etc directory. +
```
   
+   # ls -l  /usr/vice/etc
+
```
+
If either or both of /usr/vice/etc/ThisCell and +/usr/vice/etc/CellServDB do not exist, or are not links, issue the +following commands. +
```
   
+   # cd /usr/vice/etc
+   
+   # ln -s /usr/afs/etc/ThisCell
+   
+   # ln -s /usr/afs/etc/CellServDB 
+    
+
```
+

+ + + + + + + + + + + + + + + + + +

Defining Cell Name and Membership for Server Processes

Now assign your cell's name. The chapter in the +IBM AFS Administration Guide about cell configuration and +administration issues discusses the important considerations, explains why +changing the name is difficult, and outlines the restrictions on name +format. Two of the most important restrictions are that the name cannot +include uppercase letters or more than 64 characters. +

Use the bos setcellname command to assign the cell name. +It creates two files: +

/usr/afs/etc/ThisCell, which defines this machine's cell +membership +
/usr/afs/etc/CellServDB, which lists the cell's database +server machines; the machine named on the command line is placed on the +list automatically +

Note:

In the following and every instruction in this guide, for the +machine name argument substitute the fully-qualified hostname +(such as fs1.abc.com) of the machine you are +installing. For the cell name argument substitute your +cell's complete name (such as abc.com). +

+ + +

Issue the bos setcellname command to set the cell name. +
```
   
+   # cd /usr/afs/bin
+      
+   # ./bos setcellname <machine name> <cell name> -noauth
+
```
+
Because you are not authenticated and authorization checking is disabled, +the bos command interpreter possibly produces error messages about +being unable to obtain tickets and running unauthenticated. You can +safely ignore the messages. + + + + +
Issue the bos listhosts command to verify that the machine you +are installing is now registered as the cell's first database server +machine. +
```
   
+   # ./bos listhosts <machine name> -noauth
+   Cell name is cell_name
+       Host 1 is machine_name
+   
+
```
+

+ + + + + + + + + + + + + + + + + + + + + + + + + +

Starting the Database Server Processes

Next use the bos create command to create entries +for the four database server processes in the +/usr/afs/local/BosConfig file and start them running. The +four processes run on database server machines only: +

The Authentication Server (the kaserver process) maintains the +Authentication Database +
The Backup Server (the buserver process) maintains the Backup +Database +
The Protection Server (the ptserver process) maintains the +Protection Database +
The Volume Location (VL) Server (the vlserver process) +maintains the Volume Location Database (VLDB) +

+ +

Note:

AFS's authentication and authorization software is based on algorithms +and other procedures known as Kerberos, as originally developed by +Project Athena at the Massachusetts Institute of Technology. Some cells +choose to replace the AFS Authentication Server and other security-related +protocols with Kerberos as obtained directly from Project Athena or other +sources. If you wish to do this, contact the AFS Product Support group +now to learn about necessary modifications to the installation. +

The remaining instructions in this chapter include the -cell +argument on all applicable commands. Provide the cell name you assigned +in Defining Cell Name and Membership for Server Processes. If a command appears on multiple lines, it is only +for legibility. + + +

Issue the bos create command to start the Authentication +Server. The current working directory is still +/usr/afs/bin. +
```
   
+   # ./bos create <machine name> kaserver simple /usr/afs/bin/kaserver  \
+                  -cell <cell name>  -noauth   
+
```
+
You can safely ignore the messages that tell you to add Kerberos to the +/etc/services file; AFS uses a default value that makes the +addition unnecessary. You can also ignore messages about the failure of +authentication. +

Issue the bos create command to start the Backup Server. +

   
+   # ./bos create <machine name> buserver simple /usr/afs/bin/buserver  \
+                  -cell <cell name>  -noauth
+   
+

Issue the bos create command to start the Protection +Server. +

   
+   # ./bos create <machine name> ptserver simple /usr/afs/bin/ptserver  \
+                  -cell <cell name>  -noauth
+   
+

Issue the bos create command to start the VL Server. +

   
+   # ./bos create <machine name> vlserver simple /usr/afs/bin/vlserver  \
+                  -cell <cell name>  -noauth
+   
+

+ + + + + + + + + + + + + +

Initializing Cell Security

Now initialize the cell's security mechanisms. +Begin by creating the following two initial entries in the Authentication +Database: +

A generic administrative account, called admin by +convention. If you choose to assign a different name, substitute it +throughout the remainder of this document. +
After you complete the installation of the first machine, you can continue +to have all administrators use the admin account, or you can create +a separate administrative account for each of them. The latter scheme +implies somewhat more overhead, but provides a more informative audit trail +for administrative operations. +
The entry for AFS server processes, called afs. No user +logs in under this identity, but the Authentication Server's Ticket +Granting Service (TGS) module uses the associated key to encrypt the server +tickets that it grants to AFS clients for presentation to server processes +during mutual authentication. (The chapter in the IBM AFS +Administration Guide about cell configuration and administration +describes the role of server encryption keys in mutual authentication.) +
In Step 7, you also place the initial AFS server encryption key into +the /usr/afs/etc/KeyFile file. The AFS server processes +refer to this file to learn the server encryption key when they need to +decrypt server tickets. +

You also issue several commands that enable the new admin user +to issue privileged commands in all of the AFS suites. +

The following instructions do not configure all of the security mechanisms +related to the AFS Backup System. See the chapter in the IBM AFS +Administration Guide about configuring the Backup System. +

Enter kas interactive mode. Because the machine is in +no-authorization checking mode, include the -noauth flag to +suppress the Authentication Server's usual prompt for a password. +
```
   
+   # kas  -cell <cell name> -noauth 
+   ka>
+  
+
```
+ + + + +
Issue the kas create command to create Authentication +Database entries called admin and afs. +
Do not provide passwords on the command line. Instead provide them +as afs_passwd and admin_passwd in response to the +kas command interpreter's prompts as shown, so that they do +not appear on the standard output stream. +
You need to enter the afs_passwd string only in this step and in +Step 7, so provide a value that is as long and complex as possible, +preferably including numerals, punctuation characters, and both uppercase and +lowercase letters. Also make the admin_passwd as long and +complex as possible, but keep in mind that administrators need to enter it +often. Both passwords must be at least six characters long. +
```
   
+   ka> create afs 
+   initial_password:  afs_passwd
+   Verifying, please re-enter initial_password: afs_passwd
+    
+   ka> create admin
+   initial_password: admin_passwd
+   Verifying, please re-enter initial_password: admin_passwd
+   
+
```
+ + + +
Issue the kas examine command to display the +afs entry. The output includes a checksum generated by +encrypting a constant with the server encryption key derived from the +afs_passwd string. In Step 8 you issue the bos listkeys command to verify +that the checksum in its output matches the checksum in this output. +
```
   
+   ka> examine afs
+   User data for afs
+    key (0) cksum is checksum . . .
+   
+
```
+ + + +
Issue the kas setfields command to turn on the +ADMIN flag in the admin entry. This enables the +admin user to issue privileged kas commands. Then +issue the kas examine command to verify that the ADMIN +flag appears in parentheses on the first line of the output, as shown in the +example. +
```
   
+   ka> setfields admin -flags admin
+   
+   ka> examine admin 
+   User data for admin (ADMIN) . . .
+     
+
```
+ + + +
Issue the kas quit command to leave kas interactive +mode. +
```
   
+   ka> quit
+   
+
```
+ + + + + + + +
Issue the bos adduser command to add the +admin user to the /usr/afs/etc/UserList file. +This enables the admin user to issue privileged bos and +vos commands. +
```
   
+   # ./bos adduser <machine name> admin -cell <cell name> -noauth
+   
+
```
+ + + + +
Issue the bos addkey command to define the AFS server +encryption key in the /usr/afs/etc/KeyFile file. +
Do not provide the password on the command line. Instead provide it +as afs_passwd in response to the bos command +interpreter's prompts, as shown. Provide the same string as in +Step 2. +
```
   
+   # ./bos addkey <machine name> -kvno 0 -cell <cell name>  -noauth
+   Input key: afs_passwd
+   Retype input key: afs_passwd
+   
+
```
+ + + +

Issue the bos listkeys command to verify that the +checksum for the new key in the KeyFile file is the same as the +checksum for the key in the Authentication Database's afs +entry, which you displayed in Step 3. +

   
+   # ./bos listkeys <machine name> -cell <cell name> -noauth
+   key 0 has cksum checksum    
+

You can safely ignore any error messages indicating that bos +failed to get tickets or that authentication failed. +

If the keys are different, issue the following commands, making sure that +the afs_passwd string is the same in each case. The +checksum strings reported by the kas examine and bos +listkeys commands must match; if they do not, repeat these +instructions until they do, using the -kvno argument to increment +the key version number each time. +

   
+   # ./kas  -cell <cell name> -noauth 
+       
+   ka> setpassword afs -kvno 1 
+   new_password: afs_passwd
+   Verifying, please re-enter initial_password: afs_passwd
+   
+   ka> examine afs
+   User data for afs
+    key (1) cksum is checksum . . .
+  
+   ka> quit
+  
+   # ./bos addkey <machine name> -kvno 1 -cell <cell name> -noauth 
+   Input key: afs_passwd
+   Retype input key: afs_passwd
+   
+   # ./bos listkeys <machine name> -cell <cell name> -noauth
+   key 1 has cksum checksum
+   
+

+ + + +

Issue the pts createuser command to create a Protection +Database entry for the admin user. +
By default, the Protection Server assigns AFS UID 1 (one) to the +admin user, because it is the first user entry you are +creating. If the local password file (/etc/passwd or +equivalent) already has an entry for admin that assigns it a UNIX +UID other than 1, it is best to use the -id argument to the +pts createuser command to make the new AFS UID match the existing +UNIX UID. Otherwise, it is best to accept the default. +
```
   
+   # ./pts createuser -name admin -cell <cell name> [-id <AFS UID>]  -noauth
+   User admin has id AFS UID
+   
+
```
+ + + + +
Issue the pts adduser command to make the admin user +a member of the system:administrators group, and the pts +membership command to verify the new membership. Membership in +the group enables the admin user to issue privileged pts +commands and some privileged fs commands. +
```
   
+   # ./pts adduser admin system:administrators -cell <cell name> -noauth
+   
+   # ./pts membership admin -cell  <cell name> -noauth
+   Groups admin (id: 1) is a member of:
+     system:administrators
+   
+
```
+ + + + +
Issue the bos restart command with the -all flag to +restart the database server processes, so that they start using the new server +encryption key. +
```
   
+   # ./bos restart <machine name> -all -cell <cell name> -noauth
+   
+
```
+

+ + + + + + + + + + + + +

Starting the File Server, Volume Server, and Salvager

Start the fs process, which consists of the File +Server, Volume Server, and Salvager (fileserver, +volserver and salvager processes). +

Issue the bos create command to start the fs +process. The command appears here on multiple lines only for +legibility. +
```
   
+   # ./bos create  <machine name> fs fs /usr/afs/bin/fileserver   \
+                   /usr/afs/bin/volserver /usr/afs/bin/salvager  \
+                   -cell <cell name>  -noauth   
+
```
+
Sometimes a message about Volume Location Database (VLDB) initialization +appears, along with one or more instances of an error message similar to the +following: +
```
   
+   FSYNC_clientInit temporary failure (will retry)   
+
```
+
This message appears when the volserver process tries to start +before the fileserver process has completed its +initialization. Wait a few minutes after the last such message before +continuing, to guarantee that both processes have started successfully. + + +
You can verify that the fs process has started successfully by +issuing the bos status command. Its output mentions two +proc starts. +
```
  
+   # ./bos status <machine name> fs -long -noauth
+   
+
```
+
Your next action depends on whether you have ever run AFS file server +machines in the cell: +
- If you are installing the first AFS server machine ever in the cell (that +is, you are not upgrading the AFS software from a previous version), create +the first AFS volume, root.afs. +
  For the partition name argument, substitute the name of one of +the machine's AFS server partitions (such as /vicepa). +
```
  
+   # ./vos create  <machine name> <partition name> root.afs   \
+                   -cell <cell name>  -noauth   
+
```
  +
  The Volume Server produces a message confirming that it created the volume +on the specified partition. You can ignore error messages indicating +that tokens are missing, or that authentication failed. + + + + +
- If there are existing AFS file server machines and volumes in the cell, +issue the vos syncvldb and vos syncserv commands to +synchronize the VLDB with the actual state of volumes on the local +machine. To follow the progress of the synchronization operation, which +can take several minutes, use the -verbose flag. +
```
  
+   # ./vos syncvldb <machine name> -cell <cell name> -verbose  -noauth
+  
+   # ./vos syncserv <machine name> -cell <cell name> -verbose  -noauth   
+
```
  +
  You can ignore error messages indicating that tokens are missing, or that +authentication failed. +
+

+ + + + + + + + +

Starting the Server Portion of the Update Server

Start the server portion of the Update Server (the +upserver process), to distribute the contents of directories on +this machine to other server machines in the cell. It becomes active +when you configure the client portion of the Update Server on additional +server machines. +

Distributing the contents of its /usr/afs/etc directory makes +this machine the cell's system control machine. The +other server machines in the cell run the upclientetc process (an +instance of the client portion of the Update Server) to retrieve the +configuration files. Use the -crypt argument to the +upserver initialization command to specify that the Update Server +distributes the contents of the /usr/afs/etc directory only in +encrypted form, as shown in the following instruction. Several of the +files in the directory, particularly the KeyFile file, are crucial +to cell security and so must never cross the network unencrypted. +

(You can choose not to configure a system control machine, in which case +you must update the configuration files in each server machine's +/usr/afs/etc directory individually. The bos +commands used for this purpose also encrypt data before sending it across the +network.) +

Distributing the contents of its /usr/afs/bin directory to other +server machines of its system type makes this machine a binary +distribution machine. The other server machines of its system +type run the upclientbin process (an instance of the client portion +of the Update Server) to retrieve the binaries. +

The binaries in the /usr/afs/bin directory are not sensitive, so +it is not necessary to encrypt them before transfer across the network. +Include the -clear argument to the upserver +initialization command to specify that the Update Server distributes the +contents of the /usr/afs/bin directory in unencrypted form unless +an upclientbin process requests encrypted transfer. +

Note that the server and client portions of the Update Server always +mutually authenticate with one another, regardless of whether you use the +-clear or -crypt arguments. This protects their +communications from eavesdropping to some degree. +

For more information on the upclient and upserver +processes, see their reference pages in the IBM AFS Administration +Reference. The commands appear on multiple lines here only for +legibility. +

Issue the bos create command to start the upserver +process. +

   
+   # ./bos create  <machine name> upserver simple  \ 
+             "/usr/afs/bin/upserver  -crypt /usr/afs/etc    \
+             -clear /usr/afs/bin" -cell <cell name>  -noauth 
+   
+

+ + + + + + +

Starting the Controller for NTPD

Keeping the clocks on all server and client machines in your +cell synchronized is crucial to several functions, and in particular to the +correct operation of AFS's distributed database technology, Ubik. +The chapter in the IBM AFS Administration Guide about administering +server machines explains how time skew can disturb Ubik's performance and +cause service outages in your cell. +

The AFS distribution includes a version of the Network Time Protocol Daemon +(NTPD) for synchronizing the clocks on server machines. If a time +synchronization program is not already running on the machine, then in this +section you start the runntp process to configure NTPD for use with +AFS. +
Note: Do not run the runntp process if NTPD or another time +synchronization protocol is already running on the machine. Some +versions of some operating systems run a time synchronization program by +default, as detailed in the IBM AFS Release Notes. +
Attempting to run multiple instances of the NTPD causes an error. +Running NTPD together with another time synchronization protocol is +unnecessary and can cause instability in the clock setting. +
+

If you run the runntp process and your cell has reliable network +connectivity to machines outside your cell, then it is conventional to +configure the first AFS machine to refer to a time source outside the +cell. When you later install the runntp program on other +server machines in the cell, it configures NTPD to choose a time source at +random from among the database server machines listed in the +/usr/afs/etc/CellServDB file. Time synchronization therefore +works in a chained manner: this database server machine refers to a time +source outside the cell, the database server machines refer to the machine +among them that has access to the most accurate time (NTPD itself includes +code for determining this), and each non-database server machine refers to a +local database server machine chosen at random from the +/usr/afs/etc/CellServDB file. If you ever decide to remove +database server functionality from this machine, it is best to transfer +responsibility for consulting an external time source to a remaining database +server machine. +

If your cell does not have network connectivity to external machines, or if +the connectivity is not reliable, include the -localclock flag to +the runntp command as indicated in the following +instructions. The flag tells NTPD to rely on the machine's +internal clock when all external time sources are inaccessible. The +runntp command has other arguments that are possibly useful given +your cell configuration; see the IBM AFS Administration +Reference. +

Choosing an appropriate external time source is important, but involves +more considerations than can be discussed here. If you need help in +selecting a source, contact the AFS Product Support group. +

As the runntp process initializes NTPD, trace messages sometimes +appear on the standard output stream. You can ignore them, but they can +be informative if you understand how NTPD works. +

Issue the bos create command to start the runntp +process. For the host argument, substitute the fully-qualified +hostname or IP address of one or more machines outside the cell that are to +serve as time sources. Separate each name with a space. +
- If your cell usually has reliable network connectivity to an external time +source, use the following command: +
```
   
+   # ./bos create  <machine name>   runntp simple   \
+        "/usr/afs/bin/runntp <host>+"  -cell <cell name>  -noauth
+   
+
```
  +
- If your cell does not have network connectivity to an external time +source, use the following command: +
```
   
+   # ./bos create  <machine name> runntp simple  \ 
+        "/usr/afs/bin/runntp -localclock"  -cell <cell name>  -noauth
+   
+
```
  +
- If your cell has network connectivity to an external time source, but the +network connection is frequently interrupted, use the following command: +
  +
```
   
+   # ./bos create  <machine name> runntp simple  \ 
+         "/usr/afs/bin/runntp -localclock <host>+"  \
+         -cell <cell name>  -noauth
+   
+
```
  +
+

+ + + +

Overview: Installing Client Functionality

The machine you are installing is now an AFS file server +machine, database server machine, system control machine, and binary +distribution machine. Now make it a client machine by completing the +following tasks: +

Define the machine's cell membership for client processes +
Create the client version of the CellServDB file +
Define cache location and size +
Create the /afs directory and start the Cache Manager +

+ + + +

Copying Client Files to the Local Disk

Before installing and configuring the AFS client, copy the +necessary files from the AFS CD-ROM to the local /usr/vice/etc +directory. +

On the local /cdrom directory, mount the AFS CD-ROM for this +machine's system type, if it is not already. For instructions on +mounting CD-ROMs (either locally or remotely via NFS), consult the operating +system documentation. +
Copy files to the local /usr/vice/etc directory. +
This step places a copy of the AFS initialization script (and related +files, if applicable) into the /usr/vice/etc directory. In +the preceding instructions for incorporating AFS into the kernel, you copied +the script directly to the operating system's conventional location for +initialization files. When you incorporate AFS into the machine's +startup sequence in a later step, you can choose to link the two files. +
On some system types that use a dynamic kernel loader program, you +previously copied AFS library files into a subdirectory of the +/usr/vice/etc directory. On other system types, you copied +the appropriate AFS library file directly to the directory where the operating +system accesses it. The following commands do not copy or recopy the +AFS library files into the /usr/vice/etc directory, because on some +system types the library files consume a large amount of space. If you +want to copy them, add the -r flag to the first cp +command and skip the second cp command. +
```
   
+   # cd /cdrom/sysname/root.client/usr/vice/etc
+   
+   # cp -p  *  /usr/vice/etc
+  
+   # cp -rp  C  /usr/vice/etc
+   
+
```
+

+ + + + + + + +

Defining Cell Membership for Client Processes

Every AFS client machine has a copy of the +/usr/vice/etc/ThisCell file on its local disk to define the +machine's cell membership for the AFS client programs that run on +it. The ThisCell file you created in the +/usr/afs/etc directory (in Defining Cell Name and Membership for Server Processes) is used only by server processes. +

Among other functions, the ThisCell file on a client machine +determines the following: +

The cell in which users authenticate when they log onto the machine, +assuming it is using an AFS-modified login utility +
The cell in which users authenticate by default when they issue the +klog command +
The cell membership of the AFS server processes that the AFS command +interpreters on this machine contact by default +

Change to the /usr/vice/etc directory and remove the symbolic +link created in Starting the BOS Server. +
```
      
+   # cd /usr/vice/etc
+   
+   # rm ThisCell
+   
+
```
+
Create the ThisCell file as a copy of the +/usr/afs/etc/ThisCell file. Defining the same local cell for +both server and client processes leads to the most consistent AFS +performance. +
```
   
+   # cp  /usr/afs/etc/ThisCell  ThisCell
+   
+
```
+

+ + + + + + + + +

Creating the Client CellServDB File

The /usr/vice/etc/CellServDB file on a client +machine's local disk lists the database server machines for each cell +that the local Cache Manager can contact. If there is no entry in the +file for a cell, or if the list of database server machines is wrong, then +users working on this machine cannot access the cell. The chapter in +the IBM AFS Administration Guide about administering client +machines explains how to maintain the file after creating it. +

As the afsd program initializes the Cache Manager, it copies the +contents of the CellServDB file into kernel memory. The +Cache Manager always consults the list in kernel memory rather than the +CellServDB file itself. Between reboots of the machine, you +can use the fs newcell command to update the list in kernel memory +directly; see the chapter in the IBM AFS Administration Guide +about administering client machines. +

The AFS distribution includes the file CellServDB.sample, +and you have already copied it to the /usr/vice/etc +directory. It includes an entry for all AFS cells that agreed to share +their database server machine information at the time your AFS CD-ROM was +created. The AFS Product Support group also maintains a copy of the +file, updating it as necessary. If you are interested in participating +in the global AFS namespace, it is a good policy to consult the file +occasionally for updates. Ask the AFS Product Support group for a +pointer to its location. +

The CellServDB.sample file can be a good basis for the +client CellServDB file, because all of the entries in it use the +correct format. You can add or remove cell entries as you see +fit. Later (in Enabling Access to Foreign Cells) you perform additional steps that enable the Cache +Manager actually to reach the cells. +

In this section, you add an entry for the local cell to the local +CellServDB file. The current working directory is still +/usr/vice/etc. +

Remove the symbolic link created in Starting the BOS Server and rename the CellServDB.sample file to +CellServDB. +
```
   
+   # rm CellServDB
+  
+   # mv CellServDB.sample CellServDB
+      
+
```
+
Add an entry for the local cell to the CellServDB file. +One easy method is to use the cat command to append the contents of +the server /usr/afs/etc/CellServDB file to the client +version. +
```
   
+    # cat  /usr/afs/etc/CellServDB >>  CellServDB   
+
```
+
Then open the file in a text editor to verify that there are no blank +lines, and that all entries have the required format, which is described just +following. The ordering of cells is not significant, but it can be +convenient to have the client machine's home cell at the top; move +it there now if you wish. +
- The first line of a cell's entry has the following format: +
```
   
+   >cell_name      #organization   
+
```
  +
  where cell_name is the cell's complete Internet domain name +(for example, abc.com) and organization is an +optional field that follows any number of spaces and the number sign +(#). By convention it names the organization to which the +cell corresponds (for example, the ABC Corporation). +
- After the first line comes a separate line for each database server +machine. Each line has the following format: +
```
   
+   IP_address   #machine_name   
+
```
  +
  where IP_address is the machine's IP address in dotted +decimal format (for example, 192.12.105.3). +Following any number of spaces and the number sign (#) is +machine_name, the machine's fully-qualified hostname (for +example, db1.abc.com). In this case, the +number sign does not indicate a comment; machine_name is a +required field. +
+
If the file includes cells that you do not wish users of this machine to +access, remove their entries. +

The following example shows entries for two cells, each of which has three +database server machines: +

   
+   >abc.com       #ABC Corporation (home cell)
+   192.12.105.3      #db1.abc.com
+   192.12.105.4      #db2.abc.com
+   192.12.105.55     #db3.abc.com
+   >stateu.edu    #State University cell
+   138.255.68.93     #serverA.stateu.edu
+   138.255.68.72     #serverB.stateu.edu
+   138.255.33.154    #serverC.stateu.edu
+   
+

+ + + + +

Configuring the Cache

The Cache Manager uses a cache on the local disk or in +machine memory to store local copies of files fetched from file server +machines. As the afsd program initializes the Cache Manager, +it sets basic cache configuration parameters according to definitions in the +local /usr/vice/etc/cacheinfo file. The file has three +fields: +

The first field names the local directory on which to mount the AFS +filespace. The conventional location is the /afs +directory. +
The second field defines the local disk directory to use for the disk +cache. The conventional location is the /usr/vice/cache +directory, but you can specify an alternate directory if another partition has +more space available. There must always be a value in this field, but +the Cache Manager ignores it if the machine uses a memory cache. +
The third field specifies the number of kilobyte (1024 byte) blocks to +allocate for the cache. +

The values you define must meet the following requirements. +

On a machine using a disk cache, the Cache Manager expects always to be +able to use the amount of space specified in the third field. Failure +to meet this requirement can cause serious problems, some of which can be +repaired only by rebooting. You must prevent non-AFS processes from +filling up the cache partition. The simplest way is to devote a +partition to the cache exclusively. +
The amount of space available in memory or on the partition housing the +disk cache directory imposes an absolute limit on cache size. +
The maximum supported cache size can vary in each AFS release; see +the IBM AFS Release Notes for the current version. +
For a disk cache, you cannot specify a value in the third field that +exceeds 95% of the space available on the partition mounted at the directory +named in the second field. If you violate this restriction, the +afsd program exits without starting the Cache Manager and prints an +appropriate message on the standard output stream. A value of 90% is +more appropriate on most machines. Some operating systems (such as AIX) +do not automatically reserve some space to prevent the partition from filling +completely; for them, a smaller value (say, 80% to 85% of the space +available) is more appropriate. +
For a memory cache, you must leave enough memory for other processes and +applications to run. If you try to allocate more memory than is +actually 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
+
```
+
The number value is how many kilobytes were allocated just before +the failure, and so indicates the approximate amount of memory +available. +

Within these hard limits, the factors that determine appropriate cache size +include the number of users working on the machine, the size of the files with +which they work, and (for a memory cache) the number of processes that run on +the machine. The higher the demand from these factors, the larger the +cache needs to be to maintain good performance. +

Configuring a Disk Cache

Note:

Not all file system types that an operating system supports are +necessarily supported for use as the cache partition. For possible +restrictions, see the IBM AFS Release Notes. +

To configure the disk cache, perform the following procedures: +

Create the local directory to use for caching. The following +instruction shows the conventional location, +/usr/vice/cache. If you are devoting a partition exclusively +to caching, as recommended, you must also configure it, make a file system on +it, and mount it at the directory created in this step. +
```
   
+   # mkdir /usr/vice/cache
+   
+
```
+
Create the cacheinfo file to define the configuration +parameters discussed previously. The following instruction shows the +standard mount location, /afs, and the standard cache location, +/usr/vice/cache. +
```
   
+   # echo "/afs:/usr/vice/cache:#blocks" > /usr/vice/etc/cacheinfo
+
```
+
The following example defines the disk cache size as 50,000 KB: +
```
   
+   # echo "/afs:/usr/vice/cache:50000" > /usr/vice/etc/cacheinfo
+
```
+

Configuring a Memory Cache

To configure a memory cache, create the cacheinfo +file to define the configuration parameters discussed previously. The +following instruction shows the standard mount location, /afs, and +the standard cache location, /usr/vice/cache (though the exact +value of the latter is irrelevant for a memory cache). +

   
+   # echo "/afs:/usr/vice/cache:#blocks" > /usr/vice/etc/cacheinfo
+

The following example allocates 25,000 KB of memory for the cache. +

   
+   # echo "/afs:/usr/vice/cache:25000" > /usr/vice/etc/cacheinfo
+

+ + + + + + +

Configuring the Cache Manager

By convention, the Cache Manager mounts the AFS filespace on +the local /afs directory. In this section you create that +directory. +

The afsd program sets several cache configuration parameters as +it initializes the Cache Manager, and starts daemons that improve +performance. You can use the afsd command's arguments +to override the parameters' default values and to change the number of +some of the daemons. Depending on the machine's cache size, its +amount of RAM, and how many people work on it, you can sometimes improve Cache +Manager performance by overriding the default values. For a discussion +of all of the afsd command's arguments, see its reference page +in the IBM AFS Administration Reference. +

The afsd command line in the AFS initialization script on each +system type includes an OPTIONS variable. You can use it to +set nondefault values for the command's arguments, in one of the +following ways: +

You can create an afsd options file that sets values +for arguments to the afsd command. If the file exists, its +contents are automatically substituted for the OPTIONS variable in +the AFS initialization script. The AFS distribution for some system +types includes an options file; on other system types, you must create +it. +
You use two variables in the AFS initialization script to specify the path +to the options file: CONFIG and AFSDOPT. On +system types that define a conventional directory for configuration files, the +CONFIG variable indicates it by default; otherwise, the +variable indicates an appropriate location. +
List the desired afsd options on a single line in the options +file, separating each option with one or more spaces. The following +example sets the -stat argument to 2500, the -daemons +argument to 4, and the -volumes argument to 100. +
```
   
+   -stat 2500 -daemons 4 -volumes 100   
+   
+
```
+
On a machine that uses a disk cache, you can set the OPTIONS +variable in the AFS initialization script to one of $SMALL, +$MEDIUM, or $LARGE. The AFS initialization script +uses one of these settings if the afsd options file named by the +AFSDOPT variable does not exist. In the script as +distributed, the OPTIONS variable is set to the value +$MEDIUM. +
Note: Do not set the OPTIONS variable to $SMALL, +$MEDIUM, or $LARGE on a machine that uses a memory +cache. The arguments it sets are appropriate only on a machine that +uses a disk cache. +
+
The script (or on some system types the afsd options file named +by the AFSDOPT variable) defines a value for each of +SMALL, MEDIUM, and LARGE that sets +afsd command arguments appropriately for client machines of +different sizes: +
- SMALL is suitable for a small machine that serves one or two +users and has approximately 8 MB of RAM and a 20-MB cache +
- MEDIUM is suitable for a medium-sized machine that serves two +to six users and has 16 MB of RAM and a 40-MB cache +
- LARGE is suitable for a large machine that serves five to ten +users and has 32 MB of RAM and a 100-MB cache +
+
You can choose not to create an afsd options file and to set +the OPTIONS variable in the initialization script to a null value +rather than to the default $MEDIUM value. You can then +either set arguments directly on the afsd command line in the +script, or set no arguments (and so accept default values for all Cache +Manager parameters). +

Create the local directory on which to mount the AFS filespace, by +convention /afs. If the directory already exists, verify +that it is empty. +
```
   
+   # mkdir /afs
+   
+
```
+
On AIX systems, add the following line to the /etc/vfs +file. It enables AIX to unmount AFS correctly during shutdown. +
```
   
+   afs     4     none     none
+   
+
```
+
On Linux systems, copy the afsd options file from the +/usr/vice/etc directory to the /etc/sysconfig directory, +removing the .conf extension as you do so. +
```
   
+   # cp /usr/vice/etc/afs.conf /etc/sysconfig/afs
+   
+
```
+
Edit the machine's AFS initialization script or afsd +options file to set appropriate values for afsd command +parameters. The script resides in the indicated location on each system +type: +
- On AIX systems, /etc/rc.afs +
- On Digital UNIX systems, /sbin/init.d/afs +
- On HP-UX systems, /sbin/init.d/afs +
- On IRIX systems, /etc/init.d/afs +
- On Linux systems, /etc/sysconfig/afs (the afsd +options file) +
- On Solaris systems, /etc/init.d/afs +
+
Use one of the methods described in the introduction to this section to add +the following flags to the afsd command line. If you intend +for the machine to remain an AFS client, also set any performance-related +arguments you wish. +
- Add the -nosettime flag, because this is a file server machine +that is also a client. The flag prevents the machine from picking a +file server machine in the cell as its source for the correct time, which +client machines normally do. File server machines instead use NTPD (as +controlled by the runntp process) or another protocol to +synchronize their clocks. +
- Add the -memcache flag if the machine is to use a memory +cache. +
- Add the -verbose flag to display a trace of the Cache +Manager's initialization on the standard output stream. +
+

+ + +

Overview: Completing the Installation of the First AFS Machine

The machine is now configured as an AFS file server and +client machine. In this final phase of the installation, you initialize +the Cache Manager and then create the upper levels of your AFS filespace, +among other procedures. The procedures are: +

Verify that the initialization script works correctly, and incorporate it +into the operating system's startup and shutdown sequence +
Create and mount top-level volumes +
Create and mount volumes to store system binaries in AFS +
Enable access to foreign cells +
Institute additional security measures +
Remove client functionality if desired +

+ + + + + +

Verifying the AFS Initialization Script

At this point you run the AFS initialization script to verify +that it correctly invokes all of the necessary programs and AFS processes, and +that they start correctly. The following are the relevant +commands: +

The command that dynamically loads AFS modifications into the kernel, on +some system types (not applicable if the kernel has AFS modifications built +in) +
The bosserver command, which starts the BOS Server; it in +turn starts the server processes for which you created entries in the +/usr/afs/local/BosConfig file +
The afsd command, which initializes the Cache Manager +

On system types that use a dynamic loader program, you must reboot the +machine before running the initialization script, so that it can freshly load +AFS modifications into the kernel. +

If there are problems during the initialization, attempt to resolve +them. The AFS Product Support group can provide assistance if +necessary. +

Issue the bos shutdown command to shut down the AFS server +processes other than the BOS Server. Include the -wait flag +to delay return of the command shell prompt until all processes shut down +completely. +
```
      
+   # /usr/afs/bin/bos shutdown <machine name> -wait
+   
+
```
+
Issue the ps command to learn the bosserver +process's process ID number (PID), and then the kill command +to stop it. +
```
   
+   # ps appropriate_ps_options | grep bosserver
+   
+   # kill bosserver_PID
+   
+
```
+
Issue the appropriate commands to run the AFS initialization script for +this system type. + +
On AIX systems: +
1. Reboot the machine and log in again as the local superuser +root. +
```
   
+   # cd /
+   
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+
```
  +
2. Run the AFS initialization script. +
```
   
+   # /etc/rc.afs
+   
+
```
  +
+ +
On Digital UNIX systems: +
1. Run the AFS initialization script. +
```
   
+   # /sbin/init.d/afs  start
+   
+
```
  +
+ +
On HP-UX systems: +
1. Run the AFS initialization script. +
```
   
+   # /sbin/init.d/afs  start
+   
+
```
  +
+ + + + + + + +
On IRIX systems: +
1. If you have configured the machine to use the ml dynamic loader +program, reboot the machine and log in again as the local superuser +root. +
```
   
+   # cd /
+   
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+
```
  +
2. Issue the chkconfig command to activate the +afsserver and afsclient configuration variables. +
```
   
+   # /etc/chkconfig -f afsserver on
+   
+   # /etc/chkconfig -f afsclient on 
+   
+
```
  +
3. Run the AFS initialization script. +
```
   
+   # /etc/init.d/afs  start
+   
+
```
  +
+ +
On Linux systems: +
1. Reboot the machine and log in again as the local superuser +root. +
```
  
+   # cd /
+         
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+
```
  +
2. Run the AFS initialization script. +
```
   
+   # /etc/rc.d/init.d/afs  start
+   
+
```
  +
+ +
On Solaris systems: +
1. Reboot the machine and log in again as the local superuser +root. +
```
   
+   # cd /
+      
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+
```
  +
2. Run the AFS initialization script. +
```
   
+   # /etc/init.d/afs  start
+   
+
```
  +
+ + +
Wait for the message that confirms that Cache Manager initialization is +complete. +
On machines that use a disk cache, it can take a while to initialize the +Cache Manager for the first time, because the afsd program must +create all of the Vn files in the cache directory. +Subsequent Cache Manager initializations do not take nearly as long, because +the Vn files already exist. +
As a basic test of correct AFS functioning, issue the klog +command to authenticate as the admin user. Provide the +password (admin_passwd) you defined in Initializing Cell Security. +
```
   
+   # /usr/afs/bin/klog admin
+   Password:  admin_passwd
+   
+
```
+ + +
Issue the tokens command to verify that the klog +command worked correctly. If it did, the output looks similar to the +following example for the abc.com cell, where +admin's AFS UID is 1. If the output does not seem +correct, resolve the problem. Changes to the AFS initialization script +are possibly necessary. The AFS Product Support group can provide +assistance as necessary. +
```
   
+   # /usr/afs/bin/tokens
+   Tokens held by the Cache Manager:
+  
+   User's (AFS ID 1) tokens for afs@abc.com [Expires May 22 11:52]
+       --End of list--
+   
+
```
+
Issue the bos status command to verify that the output for each +process reads Currently running normally. +
```
   
+   # /usr/afs/bin/bos status <machine name>
+   
+
```
+ + +
Change directory to the local file system root (/) and issue +the fs checkvolumes command. +
```
   
+   # cd /
+   
+   # /usr/afs/bin/fs checkvolumes
+   
+
```
+

+ + + + +

Activating the AFS Initialization Script

Now that you have confirmed that the AFS initialization +script works correctly, take the action necessary to have it run automatically +at each reboot. Proceed to the instructions for your system type: +

Activating the Script on AIX Systems +
Activating the Script on Digital UNIX Systems +
Activating the Script on HP-UX Systems +
Activating the Script on IRIX Systems +
Activating the Script on Linux Systems +
Activating the Script on Solaris Systems +

+ +

Activating the Script on AIX Systems

Edit the AIX initialization file, /etc/inittab, adding the +following line to invoke the AFS initialization script. Place it just +after the line that starts NFS daemons. +
```
   
+   rcafs:2:wait:/etc/rc.afs > /dev/console 2>&1 # Start AFS services
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc directories. +If you want to avoid potential confusion by guaranteeing that they are always +the same, create a link between them. You can always retrieve the +original script from the AFS CD-ROM if necessary. +
```
   
+   # cd  /usr/vice/etc
+   
+   # rm  rc.afs
+  
+   # ln -s  /etc/rc.afs
+   
+
```
+
Proceed to Configuring the Top Levels of the AFS Filespace. +

+ +

Activating the Script on Digital UNIX Systems

Change to the /sbin/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the Digital UNIX startup and shutdown +sequence. +
```
   
+   # cd  /sbin/init.d
+   
+   # ln -s  ../init.d/afs  /sbin/rc3.d/S67afs
+   
+   # ln -s  ../init.d/afs  /sbin/rc0.d/K66afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /sbin/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /sbin/init.d/afs  afs.rc
+   
+
```
+
Proceed to Configuring the Top Levels of the AFS Filespace. +

+ +

Activating the Script on HP-UX Systems

Change to the /sbin/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the HP-UX startup and shutdown sequence. +
```
   
+   # cd /sbin/init.d
+   
+   # ln -s ../init.d/afs /sbin/rc2.d/S460afs
+  
+   # ln -s ../init.d/afs /sbin/rc2.d/K800afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /sbin/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /sbin/init.d/afs  afs.rc
+   
+
```
+
Proceed to Configuring the Top Levels of the AFS Filespace. +

+ +

Activating the Script on IRIX Systems

Change to the /etc/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the IRIX startup and shutdown sequence. +
```
   
+   # cd /etc/init.d
+   
+   # ln -s ../init.d/afs /etc/rc2.d/S35afs
+  
+   # ln -s ../init.d/afs /etc/rc0.d/K35afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /etc/init.d/afs  afs.rc
+   
+
```
+
Proceed to Configuring the Top Levels of the AFS Filespace. +

+ +

Activating the Script on Linux Systems

Issue the chkconfig command to activate the afs +configuration variable. Based on the instruction in the AFS +initialization file that begins with the string #chkconfig, the +command automatically creates the symbolic links that incorporate the script +into the Linux startup and shutdown sequence. +
```
   
+   # /sbin/chkconfig  --add afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and +/etc/rc.d/init.d directories, and copies of the +afsd options file in both the /usr/vice/etc and +/etc/sysconfig directories. If you want to avoid potential +confusion by guaranteeing that the two copies of each file are always the +same, create a link between them. You can always retrieve the original +script or options file from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc afs.conf
+    
+   # ln -s  /etc/rc.d/init.d/afs  afs.rc
+   
+   # ln -s  /etc/sysconfig/afs  afs.conf
+   
+
```
+
Proceed to Configuring the Top Levels of the AFS Filespace. +

+ +

Activating the Script on Solaris Systems

Change to the /etc/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the Solaris startup and shutdown sequence. +
```
   
+   # cd /etc/init.d
+  
+   # ln -s ../init.d/afs /etc/rc3.d/S99afs
+  
+   # ln -s ../init.d/afs /etc/rc0.d/K66afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /etc/init.d/afs  afs.rc
+   
+
```
+

+ + +

Configuring the Top Levels of the AFS Filespace

If you have not previously run AFS in your cell, you now +configure the top levels of your cell's AFS filespace. If you have +run a previous version of AFS, the filespace is already configured. +Proceed to Storing AFS Binaries in AFS. + + + +

You created the root.afs volume in Starting the File Server, Volume Server, and Salvager, and the Cache Manager mounted it automatically on the local +/afs directory when you ran the AFS initialization script in Verifying the AFS Initialization Script. You now set the access control list (ACL) on the +/afs directory; creating, mounting, and setting the ACL are +the three steps required when creating any volume. +

After setting the ACL on the root.afs volume, you create +your cell's root.cell volume, mount it as a +subdirectory of the /afs directory, and set the ACL. Create +both a read/write and a regular mount point for the +root.cell volume. The read/write mount point enables +you to access the read/write version of replicated volumes when +necessary. Creating both mount points essentially creates separate +read-only and read-write copies of your filespace, and enables the Cache +Manager to traverse the filespace on a read-only path or read/write path as +appropriate. For further discussion of these concepts, see the chapter +in the IBM AFS Administration Guide about administering +volumes. + + + +

Then replicate both the root.afs and +root.cell volumes. This is required if you want to +replicate any other volumes in your cell, because all volumes mounted above a +replicated volume must themselves be replicated in order for the Cache Manager +to access the replica. +

When the root.afs volume is replicated, the Cache Manager +is programmed to access its read-only version +(root.afs.readonly) whenever possible. To make +changes to the contents of the root.afs volume (when, for +example, you mount another cell's root.cell volume at +the second level in your filespace), you must mount the +root.afs volume temporarily, make the changes, release the +volume and remove the temporary mount point. For instructions, see Enabling Access to Foreign Cells. + + + + +

Issue the fs setacl command to edit the ACL on the +/afs directory. Add an entry that grants the l +(lookup) and r (read) permissions to the +system:anyuser group, to enable all AFS users who can reach +your cell to traverse through the directory. If you prefer to enable +access only to locally authenticated users, substitute the +system:authuser group. +
Note that there is already an ACL entry that grants all seven access rights +to the system:administrators group. It is a default +entry that AFS places on every new volume's root directory. +
```
   
+   # /usr/afs/bin/fs setacl /afs system:anyuser rl
+   
+
```
+ + + + + + + +
Issue the vos create command to create the +root.cell volume. Then issue the fs +mkmount command to mount it as a subdirectory of the /afs +directory, where it serves as the root of your cell's local AFS +filespace. Finally, issue the fs setacl command to create an +ACL entry for the system:anyuser group (or +system:authuser group). +
For the partition name argument, substitute the name of one of the +machine's AFS server partitions (such as /vicepa). For +the cellname argument, substitute your cell's fully-qualified +Internet domain name (such as abc.com). +
```
   
+   # /usr/afs/bin/vos create  <machine name> <partition name> root.cell 
+   
+   # /usr/afs/bin/fs mkmount /afs/cellname  root.cell
+   
+   # /usr/afs/bin/fs setacl /afs/cellname  system:anyuser rl
+   
+
```
+ + + +
(Optional) Create a symbolic link to a shortened cell name, to +reduce the length of pathnames for users in the local cell. For +example, in the abc.com cell, /afs/abc is a link +to /afs/abc.com. +
```
     
+   # cd /afs
+   
+   # ln -s  full_cellname  short_cellname
+   
+
```
+ + + +
Issue the fs mkmount command to create a read/write mount point +for the root.cell volume (you created a regular mount point +in Step 2). +
By convention, the name of a read/write mount point begins with a period, +both to distinguish it from the regular mount point and to make it visible +only when the -a flag is used on the ls command. +
Change directory to /usr/afs/bin to make it easier to access the +command binaries. +
```
   
+   # cd /usr/afs/bin
+   
+   # ./fs mkmount   /afs/.cellname   root.cell -rw
+   
+
```
+ + + + +
Issue the vos addsite command to define a replication +site for both the root.afs and root.cell +volumes. In each case, substitute for the partition name +argument the partition where the volume's read/write version +resides. When you install additional file server machines, it is a good +idea to create replication sites on them as well. +
```
   
+   # ./vos addsite <machine name> <partition name> root.afs
+   
+   # ./vos addsite <machine name> <partition name> root.cell
+   
+
```
+ + +
Issue the fs examine command to verify that the Cache Manager +can access both the root.afs and root.cell +volumes, before you attempt to replicate them. The output lists each +volume's name, volumeID number, quota, size, and the size of the +partition that houses them. If you get an error message instead, do not +continue before taking corrective action. +
```
 
+   # ./fs examine /afs
+   
+   # ./fs examine /afs/cellname
+   
+
```
+ + + + +
Issue the vos release command to release a replica of the +root.afs and root.cell volumes to the +sites you defined in Step 5. +
```
   
+   # ./vos release root.afs
+   
+   # ./vos release root.cell
+   
+
```
+ + +
Issue the fs checkvolumes to force the Cache Manager to notice +that you have released read-only versions of the volumes, then issue the +fs examine command again. This time its output mentions the +read-only version of the volumes (root.afs.readonly +and root.cell.readonly) instead of the read/write +versions, because of the Cache Manager's bias to access the read-only +version of the root.afs volume if it exists. +
```
   
+   # ./fs checkvolumes
+   
+   # ./fs examine /afs
+   
+   # ./fs examine /afs/cellname
+   
+
```
+

+ + + + + + +

Storing AFS Binaries in AFS

In the conventional configuration, you make AFS client +binaries and configuration files available in the subdirectories of the +/usr/afsws directory on client machines (afsws is an +acronym for AFS +workstation). You can conserve +local disk space by creating /usr/afsws as a link to an AFS volume +that houses the AFS client binaries and configuration files for this system +type. +

In this section you create the necessary volumes. The conventional +location to which to link /usr/afsws is +/afs/cellname/sysname/usr/afsws, +where sysname is the appropriate system type name as specified in the +IBM AFS Release Notes. The instructions in Installing Additional Client Machines assume that you have followed the instructions in this +section. +

If you have previously run AFS in the cell, the volumes possibly already +exist. If so, you need to perform Step 8 only. +

The current working directory is still /usr/afs/bin, which +houses the fs and vos command suite binaries. In +the following commands, it is possible you still need to specify the pathname +to the commands, depending on how your PATH environment variable is +set. +

Issue the vos create command to create volumes for +storing the AFS client binaries for this system type. The following +example instruction creates volumes called sysname, +sysname.usr, and +sysname.usr.afsws. Refer to the +IBM AFS Release Notes to learn the proper value of sysname +for this system type. +
```
    
+   # vos create <machine name> <partition name> sysname
+     
+   # vos create <machine name> <partition name> sysname.usr
+     
+   # vos create <machine name> <partition name> sysname.usr.afsws
+    
+
```
+
Issue the fs mkmount command to mount the newly created +volumes. Because the root.cell volume is replicated, +you must precede the cellname part of the pathname with a period to +specify the read/write mount point, as shown. Then issue the vos +release command to release a new replica of the +root.cell volume, and the fs checkvolumes command +to force the local Cache Manager to access them. +
```
   
+   # fs mkmount -dir /afs/.cellname/sysname -vol sysname
+   
+   # fs mkmount -dir /afs/.cellname/sysname/usr  -vol sysname.usr
+   
+   # fs mkmount -dir /afs/.cellname/sysname/usr/afsws -vol sysname.usr.afsws
+   
+   # vos release root.cell
+   
+   # fs checkvolumes
+   
+
```
+
Issue the fs setacl command to grant the l +(lookup) and r (read) permissions to the +system:anyuser group on each new directory's ACL. +
```
   
+   # cd /afs/.cellname/sysname
+   
+   # fs setacl  -dir  .  usr  usr/afsws  -acl  system:anyuser rl 
+   
+
```
+ + + + + +
Issue the fs setquota command to set an unlimited +quota on the volume mounted at the +/afs/cellname/sysname/usr/afsws +directory. This enables you to copy all of the appropriate files from +the CD-ROM into the volume without exceeding the volume's quota. +
If you wish, you can set the volume's quota to a finite value after +you complete the copying operation. At that point, use the vos +examine command to determine how much space the volume is +occupying. Then issue the fs setquota command to set a quota +that is slightly larger. +
```
   
+   # fs setquota /afs/.cellname/sysname/usr/afsws  0
+   
+
```
+
Mount the AFS CD-ROM for this machine's system type on the local +/cdrom directory, if it is not already. For instructions on +mounting CD-ROMs (either locally or remotely via NFS), consult the operating +system documentation. + + + +

Copy the contents of the indicated directories from the CD-ROM into the +/afs/cellname/sysname/usr/afsws +directory. +

   
+   # cd /afs/.cellname/sysname/usr/afsws
+   
+   # cp -rp /cdrom/sysname/bin  .
+   
+   # cp -rp /cdrom/sysname/etc  .
+   
+   # cp -rp /cdrom/sysname/include  .
+   
+   # cp -rp /cdrom/sysname/lib  .
+   
+

+ + +

Issue the fs setacl command to set the ACL on each directory +appropriately. To comply with the terms of your AFS License agreement, +you must prevent unauthorized users from accessing AFS software. To +enable access for locally authenticated users only, set the ACL on the +etc, include, and lib subdirectories to grant +the l and r permissions to the +system:authuser group rather than the +system:anyuser group. The +system:anyuser group must retain the l and +r permissions on the bin subdirectory to enable +unauthenticated users to access the klog binary. To ensure +that unauthorized users are not accessing AFS software, check periodically +that the ACLs on these directories are set properly. +
```
     
+   # cd /afs/.cellname/sysname/usr/afsws
+   
+   # fs setacl  -dir etc include lib  -acl  system:authuser rl  \
+              system:anyuser none
+   
+
```
+ + +
Create /usr/afsws on the local disk as a symbolic +link to the directory +/afs/cellname/@sys/usr/afsws. You can +specify the actual system name instead of @sys if you wish, but the +advantage of using @sys is that it remains valid if you upgrade +this machine to a different system type. +
```
   
+   # ln -s /afs/cellname/@sys/usr/afsws  /usr/afsws
+   
+
```
+ + +
(Optional) To enable users to issue commands from the AFS +suites (such as fs) without having to specify a pathname to their +binaries, include the /usr/afsws/bin and /usr/afsws/etc +directories in the PATH environment variable you define in each user's +shell initialization file (such as .cshrc). +

+ + + + + + +

Storing AFS Documents in AFS

The AFS distribution includes the following documents: +

IBM AFS Release Notes +
IBM AFS Quick Beginnings +
IBM AFS User Guide +
IBM AFS Administration Reference +
IBM AFS Administration Guide +

The AFS CD-ROM for each system type has a top-level +Documentation directory, with a subdirectory for each document +format provided. The different formats are suitable for online viewing, +printing, or both. +

This section explains how to create and mount a volume to house the +documents, making them available to your users. The recommended mount +point for the volume is +/afs/cellname/afsdoc. If you wish, you +can create a link to the mount point on each client machine's local disk, +called /usr/afsdoc. Alternatively, you can create a link to +the mount point in each user's home directory. You can also choose +to permit users to access only certain documents (most probably, the IBM +AFS User Guide) by creating different mount points or setting different +ACLs on different document directories. +

The current working directory is still /usr/afs/bin, which +houses the fs and vos command suite binaries you use to +create and mount volumes. In the following commands, it is possible you +still need to specify the pathname to the commands, depending on how your PATH +environment variable is set. +

Issue the vos create command to create a volume for storing the +AFS documentation. Include the -maxquota argument to set an +unlimited quota on the volume. This enables you to copy all of the +appropriate files from the CD-ROM into the volume without exceeding the +volume's quota. +
If you wish, you can set the volume's quota to a finite value after +you complete the copying operations. At that point, use the vos +examine command to determine how much space the volume is +occupying. Then issue the fs setquota command to set a quota +that is slightly larger. +
```
   
+   # vos create  <machine name> <partition name>  afsdoc  -maxquota  0 
+     
+
```
+
Issue the fs mkmount command to mount the new volume. +Because the root.cell volume is replicated, you must precede +the cellname with a period to specify the read/write mount point, +as shown. Then issue the vos release command to release a +new replica of the root.cell volume, and the fs +checkvolumes command to force the local Cache Manager to access +them. +
```
     
+   # fs mkmount -dir /afs/.cellname/afsdoc -vol afsdoc
+   
+   # vos release root.cell
+   
+   # fs checkvolumes
+    
+
```
+
Issue the fs setacl command to grant the rl +permissions to the system:anyuser group on the new +directory's ACL. +
```
       
+   # cd /afs/.cellname/afsdoc 
+    
+   # fs setacl  .  system:anyuser rl 
+   
+
```
+
Mount the AFS CD-ROM for any system type on the local /cdrom +directory, if one is not already. For instructions on mounting CD-ROMs +(either locally or remotely via NFS), consult the operating system +documentation. + + + + + +
Copy the AFS documents in one or more formats from the CD-ROM into +subdirectories of the /afs/cellname/afsdoc +directory. Repeat the commands for each format. +
```
    
+   # mkdir format_name
+  
+   # cd format_name
+  
+   # cp -rp /cdrom/Documentation/format  .      
+
```
+
If you choose to store the HTML version of the documents in AFS, note that +in addition to a subdirectory for each document there are several files with a +.gif extension, which enable readers to move easily between +sections of a document. The file called index.htm is +an introductory HTML page that contains a hyperlink to each of the +documents. For online viewing to work properly, these files must remain +in the top-level HTML directory (the one named, for example, +/afs/cellname/afsdoc/html). +
(Optional) If you believe it is helpful to your users to access +the AFS documents in a certain format via a local disk directory, create +/usr/afsdoc on the local disk as a symbolic link to the +documentation directory in AFS +(/afs/cellname/afsdoc/format_name). +
+
```
   
+   # ln -s /afs/cellname/afsdoc/format_name /usr/afsdoc
+
```
+
An alternative is to create a link in each user's home directory to +the /afs/cellname/afsdoc/format_name +directory. +

+ + + + +

Storing System Binaries in AFS

You can also choose to store other system binaries in AFS +volumes, such as the standard UNIX programs conventionally located in local +disk directories such as /etc, /bin, and +/lib. Storing such binaries in an AFS volume not only frees +local disk space, but makes it easier to update binaries on all client +machines. +

The following is a suggested scheme for storing system binaries in +AFS. It does not include instructions, but you can use the instructions +in Storing AFS Binaries in AFS (which are for AFS-specific binaries) as a template. +

Some files must remain on the local disk for use when AFS is inaccessible +(during bootup and file server or network outages). The required +binaries include the following: +

A text editor, network commands, and so on +
Files used during the boot sequence before the afsd program +runs, such as initialization and configuration files, and binaries for +commands that mount file systems +
Files used by dynamic kernel loader programs +

In most cases, it is more secure to enable only locally authenticated users +to access system binaries, by granting the l (lookup) +and r (read) permissions to the +system:authuser group on the ACLs of directories that contain +the binaries. If users need to access a binary while unauthenticated, +however, the ACL on its directory must grant those permissions to the +system:anyuser group. +

The following chart summarizes the suggested volume and mount point names +for storing system binaries. It uses a separate volume for each +directory. You already created a volume called sysname for +this machine's system type when you followed the instructions in Storing AFS Binaries in AFS. +

You can name volumes in any way you wish, and mount them at other locations +than those suggested here. However, this scheme has several +advantages: +

Volume names clearly identify volume contents +
Using the sysname prefix on every volume makes it is easy to back +up all of the volumes together, because the AFS Backup System enables you to +define sets of volumes based on a string included in all of their names +
It makes it easy to track related volumes, keeping them together on the +same file server machine if desired +
There is a clear relationship between volume name and mount point name +

+
+ + + + + + + + + + + + + + +

Volume Name +	Mount Point +
`sysname` +	/afs/`cellname`/`sysname` +
`sysname`.bin +	/afs/`cellname`/`sysname`/bin +
`sysname`.etc +	/afs/`cellname`/`sysname`/etc +
`sysname`.usr +	/afs/`cellname`/`sysname`/usr +
`sysname`.usr.afsws +	/afs/`cellname`/`sysname`/usr/afsws +
`sysname`.usr.bin +	/afs/`cellname`/`sysname`/usr/bin +
`sysname`.usr.etc +	/afs/`cellname`/`sysname`/usr/etc +
`sysname`.usr.inc +	/afs/`cellname`/`sysname`/usr/include +
`sysname`.usr.lib +	/afs/`cellname`/`sysname`/usr/lib +
`sysname`.usr.loc +	/afs/`cellname`/`sysname`/usr/local +
`sysname`.usr.man +	/afs/`cellname`/`sysname`/usr/man +
`sysname`.usr.sys +	/afs/`cellname`/`sysname`/usr/sys +

+ + + + + + + +

Enabling Access to Foreign Cells

In this section you create a mount point in your AFS +filespace for the root.cell volume of each foreign cell that +you want to enable your users to access. For users working on a client +machine to access the cell, there must in addition be an entry for it in the +client machine's local /usr/vice/etc/CellServDB file. +(The instructions in Creating the Client CellServDB File suggest that you use the CellServDB.sample +file included in the AFS distribution as the basis for your cell's client +CellServDB file. The sample file lists all of the cells that +had agreed to participate in the AFS global namespace at the time your AFS +CD-ROM was created. As mentioned in that section, the AFS Product +Support group also maintains a copy of the file, updating it as +necessary.) +

The chapter in the IBM AFS Administration Guide about cell +administration and configuration issues discusses the implications of +participating in the global AFS namespace. The chapter about +administering client machines explains how to maintain knowledge of foreign +cells on client machines, and includes suggestions for maintaining a central +version of the file in AFS. +

Issue the fs mkmount command to mount each foreign cell's +root.cell volume on a directory called +/afs/foreign_cell. Because the +root.afs volume is replicated, you must create a temporary +mount point for its read/write version in a directory to which you have write +access (such as your cell's /afs/.cellname +directory). Create the mount points, issue the vos release +command to release new replicas to the read-only sites for the +root.afs volume, and issue the fs checkvolumes +command to force the local Cache Manager to access the new replica. +
Note: You need to issue the fs mkmount command only once for each +foreign cell's root.cell volume. You do not need +to repeat the command on each client machine. +
+
Substitute your cell's name for cellname. +
```
   
+   # cd /afs/.cellname
+   
+   # /usr/afs/bin/fs  mkmount  temp  root.afs   
+
```
+
Repeat the fs mkmount command for each foreign cell you wish to +mount at this time. +
```
   
+   # /usr/afs/bin/fs mkmount temp/foreign_cell root.cell -c foreign_cell   
+
```
+
Issue the following commands only once. +
```
     
+   # /usr/afs/bin/fs rmmount temp
+   
+   # /usr/afs/bin/vos release root.afs
+   
+   # /usr/afs/bin/fs checkvolumes
+   
+
```
+ + +
If this machine is going to remain an AFS client after you +complete the installation, verify that the local +/usr/vice/etc/CellServDB file includes an entry for each foreign +cell. +
For each cell that does not already have an entry, complete the following +instructions: +
1. Create an entry in the CellServDB file. Be sure to +comply with the formatting instructions in Creating the Client CellServDB File. +
2. Issue the fs newcell command to add an entry for the cell +directly to the list that the Cache Manager maintains in kernel memory. +Provide each database server machine's fully qualified hostname. +
```
   
+   # /usr/afs/bin/fs newcell <foreign_cell> <dbserver1>    \
+            [<dbserver2>] [<dbserver3>]
+   
+
```
  +
3. If you plan to maintain a central version of the CellServDB +file (the conventional location is +/afs/cellname/common/etc/CellServDB), create it +now as a copy of the local /usr/vice/etc/CellServDB file. +Verify that it includes an entry for each foreign cell you want your users to +be able to access. +
```
   
+   # mkdir common
+   
+   # mkdir common/etc
+   
+   # cp  /usr/vice/etc/CellServDB  common/etc
+   
+   # /usr/afs/bin/vos release root.cell
+   
+
```
  +
+
Issue the ls command to verify that the new cell's mount +point is visible in your filespace. The output lists the directories at +the top level of the new cell's AFS filespace. +
```
   
+   # ls /afs/foreign_cell
+   
+
```
+
Please register your cell with the AFS Product Support group at this +time. If you do not want to participate in the global AFS namespace, +they list your cell in a private CellServDB file that is not +available to other AFS cells. +

+ + + + + + +

Improving Cell Security

This section discusses ways to improve the security of AFS +data in your cell. Also see the chapter in the IBM AFS +Administration Guide about configuration and administration +issues. +

Controlling root Access

As on any machine, it is important to prevent unauthorized +users from logging onto an AFS server or client machine as the local superuser +root. Take care to keep the root password +secret. +

The local root superuser does not have special access to AFS +data through the Cache Manager (as members of the +system:administrators group do), but it does have the +following privileges: +

On client machines, the ability to issue commands from the fs +suite that affect AFS performance +
On server machines, the ability to disable authorization checking, or to +install rogue process binaries +

Controlling System Administrator Access

Following are suggestions for managing AFS administrative +privilege: +

Create an administrative account for each administrator named something +like username.admin. Administrators +authenticate under these identities only when performing administrative tasks, +and destroy the administrative tokens immediately after finishing the task +(either by issuing the unlog command, or the klog +command to adopt their regular identity). +
Set a short ticket lifetime for administrator accounts (for example, 20 +minutes) by using the -lifetime argument to the kas +setfields command, which is described in the IBM AFS Administration +Reference. Do not however, use a short lifetime for users who +issue long-running backup commands. +
Limit the number of system administrators in your cell, especially those +who belong to the system:administrators group. By +default they have all ACL rights on all directories in the local AFS +filespace, and therefore must be trusted not to examine private files. +
Limit the use of system administrator accounts on machines in public +areas. It is especially important not to leave such machines unattended +without first destroying the administrative tokens. +
Limit the use by administrators of standard UNIX commands that make +connections to remote machines (such as the telnet utility). +Many of these programs send passwords across the network without encrypting +them. +

+ + + +

Protecting Sensitive AFS Directories

Some subdirectories of the /usr/afs directory +contain files crucial to cell security. Unauthorized users must not +read or write to these files because of the potential for misuse of the +information they contain. +

As the BOS Server initializes for the first time on a server machine, it +creates several files and directories (as mentioned in Starting the BOS Server). It sets their owner to the local superuser +root and sets their mode bits to enable writing by the owner +only; in some cases, it also restricts reading. +

At each subsequent restart, the BOS Server checks that the owner and mode +bits on these files are still set appropriately. If they are not, it +write the following message to the /usr/afs/logs/BosLog file: +

   
+   Bosserver reports inappropriate access on server directories   
+

The BOS Server does not reset the mode bits, which enables you to set +alternate values if you wish. +

The following charts lists the expected mode bit settings. A +question mark indicates that the BOS Server does not check that mode +bit. +
+ + + + + + + + + + +
/usr/afs + drwxr?xr-x +
/usr/afs/backup + drwx???--- +
/usr/afs/bin + drwxr?xr-x +
/usr/afs/db + drwx???--- +
/usr/afs/etc + drwxr?xr-x +
/usr/afs/etc/KeyFile + -rw????--- +
/usr/afs/etc/UserList + -rw?????-- +
/usr/afs/local + drwx???--- +
/usr/afs/logs + drwxr?xr-x +
+

+ + +

Removing Client Functionality

Follow the instructions in this section only if you do not +wish this machine to remain an AFS client. Removing client +functionality means that you cannot use this machine to access AFS +files. +

Remove the files from the /usr/vice/etc directory. The +command does not remove the directory for files used by the dynamic kernel +loader program, if it exists on this system type. Those files are still +needed on a server-only machine. +
```
    
+   # cd /usr/vice/etc
+   
+   # rm  * 
+   
+   # rm -rf  C
+   
+
```
+
Create symbolic links to the ThisCell and CellServDB +files in the /usr/afs/etc directory. This makes it possible +to issue commands from the AFS command suites (such as bos and +fs) on this machine. +
```
     
+   # ln -s /usr/afs/etc/ThisCell ThisCell
+   
+   # ln -s /usr/afs/etc/CellServDB CellServDB
+   
+
```
+
On IRIX systems, issue the chkconfig command to deactivate the +afsclient configuration variable. +
```
   
+   # /etc/chkconfig -f afsclient off
+   
+
```
+
Reboot the machine. Most system types use the shutdown +command, but the appropriate options vary. +
```
   
+   # cd /
+   
+   # shutdown appropriate_options
+   
+
```
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartUnix/auqbg006.htm b/doc/html/QuickStartUnix/auqbg006.htm new file mode 100644 index 0000000..c775a91 --- /dev/null +++ b/doc/html/QuickStartUnix/auqbg006.htm @@ -0,0 +1,2270 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

+ + + +

Installing Additional Server Machines

Instructions for the following procedures appear in the +indicated section of this chapter. +

Installing an Additional File Server Machine +
Installing Database Server Functionality +
Removing Database Server Functionality +

The instructions make the following assumptions. +

You have already installed your cell's first file server machine by +following the instructions in Installing the First AFS Machine +
You are logged in as the local superuser root +
You are working at the console +
A standard version of one of the operating systems supported by the +current version of AFS is running on the machine +
You can access the data on the AFS CD-ROMs, either through a local CD-ROM +drive or via an NFS mount of a CD-ROM drive attached to a machine that is +accessible by network +

+ +

Installing an Additional File Server Machine

The procedure for installing a new file server machine is +similar to installing the first file server machine in your cell. There +are a few parts of the installation that differ depending on whether the +machine is the same AFS system type as an existing file server machine or is +the first file server machine of its system type in your cell. The +differences mostly concern the source for the needed binaries and files, and +what portions of the Update Server you install: +

On a new system type, you must load files and binaries from the AFS +CD-ROM. You install the server portion of the Update Server to make +this machine the binary distribution machine for its system type. +
On an existing system type, you can copy files and binaries from a +previously installed file server machine, rather than from the CD-ROM. +You install the client portion of the Update Server to accept updates of +binaries, because a previously installed machine of this type was installed as +the binary distribution machine. +

These instructions are brief; for more detailed information, refer to +the corresponding steps in Installing the First AFS Machine. + +

To install a new file server machine, perform the following +procedures: +

Copy needed binaries and files onto this machine's local disk +
Incorporate AFS modifications into the kernel +
Configure partitions for storing volumes +
Replace the standard fsck utility with the AFS-modified version +on some system types +
Start the Basic OverSeer (BOS) Server +
Start the appropriate portion of the Update Server +
Start the fs process, which incorporates three component +processes: the File Server, Volume Server, and Salvager +
Start the controller process (called runntp) for the Network +Time Protocol Daemon, which synchronizes clocks +

After completing the instructions in this section, you can install database +server functionality on the machine according to the instructions in Installing Database Server Functionality. + + + + + + + + + + + + + +

Creating AFS Directories and Performing Platform-Specific Procedures

Create the /usr/afs and /usr/vice/etc directories +on the local disk. Subsequent instructions copy files from the AFS +distribution CD-ROM into them, at the appropriate point for each system +type. +

      
+   # mkdir /usr/afs
+      
+   # mkdir /usr/afs/bin
+      
+   # mkdir /usr/vice
+      
+   # mkdir /usr/vice/etc
+   
+   # mkdir /cdrom     
+

As on the first file server machine, the initial procedures in installing +an additional file server machine vary a good deal from platform to +platform. For convenience, the following sections group together all of +the procedures for a system type. Most of the remaining procedures are +the same on every system type, but differences are noted as +appropriate. The initial procedures are the following. +

Incorporate AFS modifications into the kernel, either by using a dynamic +kernel loader program or by building a new static kernel +
Configure server partitions to house AFS volumes +
Replace the operating system vendor's fsck program with a +version that recognizes AFS data + +
If the machine is to remain an AFS client machine, modify the +machine's authentication system so that users obtain an AFS token as they +log into the local file system. (For this procedure only, the +instructions direct you to the platform-specific section in Installing the First AFS Machine.) +

To continue, proceed to the section for this system type: +

Getting Started on AIX Systems +
Getting Started on Digital UNIX Systems +
Getting Started on HP-UX Systems +
Getting Started on IRIX Systems +
Getting Started on Linux Systems +
Getting Started on Solaris Systems +

Getting Started on AIX Systems

Begin by running the AFS initialization script to call the +AIX kernel extension facility, which dynamically loads AFS modifications into +the kernel. Then configure partitions and replace the AIX +fsck program with a version that correctly handles AFS +volumes. +

Mount the AFS CD-ROM for AIX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your AIX documentation. Then change directory as +indicated. +
```
   
+   # cd  /cdrom/rs_aix42/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS kernel library files to the local +/usr/vice/etc/dkload directory, and the AFS initialization script +to the /etc directory. +
```
   
+   # cp -rp  dkload  /usr/vice/etc
+   
+   # cp -p  rc.afs  /etc/rc.afs
+    
+
```
+
Edit the /etc/rc.afs script, setting the NFS +variable as indicated. +
If the machine is not to function as an NFS/AFS Translator, set the +NFS variable as follows. +
```
      
+   NFS=$NFS_NONE
+
```
+
If the machine is to function as an NFS/AFS Translator and is running AIX +4.2.1 or higher, set the NFS variable as +follows. Note that NFS must already be loaded into the kernel, which +happens automatically on systems running AIX 4.1.1 and later, as +long as the file /etc/exports exists. +
```
   
+   NFS=$NFS_IAUTH
+   
+
```
+
Invoke the /etc/rc.afs script to load AFS modifications +into the kernel. You can ignore any error messages about the inability +to start the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/rc.afs
+   
+
```
+ + + + +
Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Use the SMIT program to create a journaling file system on each +partition to be configured as an AFS server partition. +
Mount each partition at one of the /vicepxx +directories. Choose one of the following three methods: +
- Use the SMIT program +
- Use the mount -a command to mount all partitions at once +
- Use the mount command on each partition in turn +
+
Also configure the partitions so that they are mounted automatically at +each reboot. For more information, refer to the AIX +documentation. + + + + +
Move the AIX fsck program helper to a safe location and install +the version from the AFS distribution in its place. The AFS CD-ROM must +still be mounted at the /cdrom directory. +
```
   
+   # cd /sbin/helpers
+   
+   # mv v3fshelper v3fshelper.noafs
+   
+   # cp -p /cdrom/rs_aix42/root.server/etc/v3fshelper v3fshelper
+   
+ 
+
```
+
If the machine is to remain an AFS client, incorporate AFS into its +authentication system, following the instructions in Enabling AFS Login on AIX Systems. +
Proceed to Starting Server Programs. +

Getting Started on Digital UNIX Systems

Begin by building AFS modifications into the kernel, then +configure server partitions and replace the Digital UNIX fsck +program with a version that correctly handles AFS volumes. +

If the machine's hardware and software configuration exactly matches +another Digital UNIX machine on which AFS is already built into the kernel, +you can copy the kernel from that machine to this one. In general, +however, it is better to build AFS modifications into the kernel on each +machine according to the following instructions. +

Create a copy called AFS of the basic kernel configuration file +included in the Digital UNIX distribution as +/usr/sys/conf/machine_name, where machine_name is +the machine's hostname in all uppercase letters. +
```
   
+   # cd /usr/sys/conf
+   
+   # cp machine_name AFS
+   
+
```
+

Add AFS to the list of options in the configuration file you created in +the previous step, so that the result looks like the following: +

          .                   .
+          .                   .
+       options               UFS
+       options               NFS
+       options               AFS
+          .                   .
+          .                   .
+   
+

Add an entry for AFS to two places in the file +/usr/sys/conf/files. +

Add a line for AFS to the list of OPTIONS, so that the result +looks like the following: +

             .                .      .
+             .                .      .
+      OPTIONS/nfs          optional nfs 
+      OPTIONS/afs          optional afs 
+      OPTIONS/nfs_server   optional nfs_server
+             .                .      .
+             .                .      .
+   
+

Add an entry for AFS to the list of MODULES, so that the result +looks like the following: +

             .                  .        .          .
+             .                  .        .          .
+      #
+      MODULE/nfs_server	    optional nfs_server Binary
+      nfs/nfs_server.c      module nfs_server optimize -g3
+      nfs/nfs3_server.c	    module nfs_server optimize -g3
+      #
+      MODULE/afs            optional afs Binary
+      afs/libafs.c          module afs
+      #
+   
+

Add an entry for AFS to two places in the file +/usr/sys/vfs/vfs_conf.c. +

Add AFS to the list of defined file systems, so that the result looks like +the following: +

        .       .              
+        .       .              
+     #include <afs.h>
+     #if defined(AFS) && AFS
+            extern struct vfsops afs_vfsops;
+     #endif  
+        .       .              
+        .       .              
+   
+

Put a declaration for AFS in the vfssw[] table's +MOUNT_ADDON slot, so that the result looks like the following: +

        .                          .              .
+        .                          .              .
+      &fdfs_vfsops,         "fdfs",   /* 12 = MOUNT_FDFS */
+   #if	defined(AFS)
+      &afs_vfsops,          "afs",
+   #else
+      (struct vfsops *)0,   "",       /* 13 = MOUNT_ADDON */
+   #endif
+   #if NFS && INFS_DYNAMIC   
+       &nfs3_vfsops,        "nfsv3",  /* 14 = MOUNT_NFS3 */		
+   
+

Mount the AFS CD-ROM for Digital UNIX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Digital UNIX documentation. Then change +directory as indicated. +
```
   
+   # cd /cdrom/alpha_dux40/root.client
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /sbin/init.d on Digital +UNIX machines). Note the removal of the .rc extension +as you copy the script. +
```
   
+   # cp usr/vice/etc/afs.rc  /sbin/init.d/afs
+   
+
```
+
Copy the AFS kernel module to the local /usr/sys/BINARY +directory. +
If the machine's kernel supports NFS server functionality: +
```
  
+   # cp bin/libafs.o /usr/sys/BINARY/afs.mod   
+
```
+
If the machine's kernel does not support NFS server +functionality: +
```
  
+   # cp bin/libafs.nonfs.o /usr/sys/BINARY/afs.mod
+   
+
```
+
Configure and build the kernel. Respond to any prompts by pressing +<Return>. The resulting kernel resides in the file +/sys/AFS/vmunix. +
```
   
+   # doconfig -c AFS
+   
+
```
+
Rename the existing kernel file and copy the new, AFS-modified file to the +standard location. +
```
   
+   # mv /vmunix /vmunix_noafs
+   
+   # cp /sys/AFS/vmunix /vmunix
+   
+
```
+

Reboot the machine to start using the new kernel, and login again as the +superuser root. +

   
+   # cd /
+   
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+

+ + + + +

Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Add a line with the following format to the file systems registry file, +/etc/fstab, for each directory just created. The entry maps +the directory name to the disk partition to be mounted on it. +
```
   
+   /dev/disk /vicepxx ufs rw 0 2
+
```
+
The following is an example for the first partition being +configured. +
```
   
+   /dev/rz3a /vicepa ufs rw 0 2
+   
+
```
+
Create a file system on each partition that is to be mounted at a +/vicepxx directory. The following command is +probably appropriate, but consult the Digital UNIX documentation for more +information. +
```
   
+   # newfs -v /dev/disk
+   
+
```
+
Mount each partition by issuing either the mount -a command to +mount all partitions at once or the mount command to mount each +partition in turn. + + + + +

Install the vfsck binary to the /sbin and +/usr/sbin directories. The AFS CD-ROM must still be mounted +at the /cdrom directory. +

   
+   # cd /cdrom/alpha_dux40/root.server/etc
+   
+   # cp vfsck /sbin/vfsck
+   
+   # cp vfsck /usr/sbin/vfsck
+   
+

Rename the Digital UNIX fsck binaries and create symbolic links +to the vfsck program. +

   
+   # cd /sbin
+   
+   # mv ufs_fsck ufs_fsck.noafs
+   
+   # ln -s vfsck ufs_fsck
+   
+   # cd /usr/sbin
+   
+   # mv ufs_fsck ufs_fsck.noafs
+   
+   # ln -s vfsck ufs_fsck
+   
+

If the machine is to remain an AFS client, incorporate AFS into its +authentication system, following the instructions in Enabling AFS Login on Digital UNIX Systems. +
Proceed to Starting Server Programs. +

Getting Started on HP-UX Systems

Begin by building AFS modifications into the kernel, then +configure server partitions and replace the HP-UX fsck program with +a version that correctly handles AFS volumes. +

If the machine's hardware and software configuration exactly matches +another HP-UX machine on which AFS is already built into the kernel, you can +copy the kernel from that machine to this one. In general, however, it +is better to build AFS modifications into the kernel on each machine according +to the following instructions. +

Move the existing kernel-related files to a safe location. +

   
+   # cp /stand/vmunix /stand/vmunix.noafs
+   
+   # cp /stand/system /stand/system.noafs
+   
+

Mount the AFS CD-ROM for HP-UX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your HP-UX documentation. Then change directory +as indicated. +
```
   
+   # cd /cdrom/hp_ux110/root.client
+   
+
```
+
Copy the AFS initialization file to the local directory for initialization +files (by convention, /sbin/init.d on HP-UX +machines). Note the removal of the .rc extension as +you copy the file. +
```
   
+   # cp usr/vice/etc/afs.rc  /sbin/init.d/afs
+   
+
```
+
Copy the file afs.driver to the local +/usr/conf/master.d directory, changing its name to +afs as you do. +
```
     
+   # cp  usr/vice/etc/afs.driver  /usr/conf/master.d/afs
+   
+
```
+
Copy the AFS kernel module to the local /usr/conf/lib +directory. +
If the machine's kernel supports NFS server functionality: +
```
   
+   # cp bin/libafs.a /usr/conf/lib   
+
```
+
If the machine's kernel does not support NFS server functionality, +change the file's name as you copy it: +
```
   
+   # cp bin/libafs.nonfs.a /usr/conf/lib/libafs.a
+   
+
```
+
Incorporate the AFS driver into the kernel, either using the +SAM program or a series of individual commands. +
- To use the SAM program: +
  1. Invoke the SAM program, specifying the hostname of the local +machine as local_hostname. The SAM graphical user +interface pops up. +
```
   
+   # sam -display local_hostname:0 
+   
+
```
    +
  2. Choose the Kernel Configuration icon, then the +Drivers icon. From the list of drivers, select +afs. +
  3. Open the pull-down Actions menu and choose the Add Driver +to Kernel option. +
  4. Open the Actions menu again and choose the Create a New +Kernel option. +
  5. Confirm your choices by choosing Yes and OK when +prompted by subsequent pop-up windows. The SAM program +builds the kernel and reboots the system. +
  6. Login again as the superuser root. +
```
   
+   login: root
+   Password: root_password
+   
+
```
    +
  +
- To use individual commands: +
  1. Edit the file /stand/system, adding an entry for afs +to the Subsystems section. +
  2. Change to the /stand/build directory and issue the +mk_kernel command to build the kernel. +
```
   
+   # cd /stand/build
+      
+   # mk_kernel
+   
+
```
    +
  3. Move the new kernel to the standard location (/stand/vmunix), +reboot the machine to start using it, and login again as the superuser +root. +
```
   
+   # mv /stand/build/vmunix_test /stand/vmunix
+      
+   # cd /
+      
+   # shutdown -r now		
+   
+   login: root
+   Password: root_password
+   
+
```
    +
  +
+ + + + +
Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Use the SAM program to create a file system on each +partition. For instructions, consult the HP-UX documentation. +
On some HP-UX systems that use logical volumes, the SAM program +automatically mounts the partitions. If it has not, mount each +partition by issuing either the mount -a command to mount all +partitions at once or the mount command to mount each partition in +turn. + + + + +
Create the command configuration file +/sbin/lib/mfsconfig.d/afs. Use a text editor to place +the indicated two lines in it: +
```
   
+   format_revision 1
+   fsck            0        m,P,p,d,f,b:c:y,n,Y,N,q,
+   
+
```
+
Create and change directory to an AFS-specific command directory called +/sbin/fs/afs. +
```
   
+   # mkdir /sbin/fs/afs
+   
+   # cd  /sbin/fs/afs
+   
+
```
+
Copy the AFS-modified version of the fsck program (the +vfsck binary) and related files from the distribution directory to +the new AFS-specific command directory. +
```
   
+   # cp -p /cdrom/hp_ux110/root.server/etc/*  .
+          
+
```
+
Change the vfsck binary's name to fsck and set +the mode bits appropriately on all of the files in the /sbin/fs/afs +directory. +
```
      
+   # mv  vfsck  fsck
+   
+   # chmod  755  *
+   
+
```
+

The sixth line in the following example of an edited file shows an AFS +server partition, /vicepa. +

   
+   /dev/vg00/lvol1 / hfs defaults 0 1
+   /dev/vg00/lvol4 /opt hfs defaults 0 2
+   /dev/vg00/lvol5 /tmp hfs defaults 0 2
+   /dev/vg00/lvol6 /usr hfs defaults 0 2
+   /dev/vg00/lvol8 /var hfs defaults 0 2
+   /dev/vg00/lvol9 /vicepa afs defaults 0 2
+   /dev/vg00/lvol7 /usr/vice/cache hfs defaults 0 2
+   
+

If the machine is to remain an AFS client, incorporate AFS into its +authentication system, following the instructions in Enabling AFS Login on HP-UX Systems. +
Proceed to Starting Server Programs. +

Getting Started on IRIX Systems

Begin by incorporating AFS modifications into the +kernel. Either use the ml dynamic loader program, or build a +static kernel. Then configure partitions to house AFS volumes. +AFS supports use of both EFS and XFS partitions for housing AFS +volumes. SGI encourages use of XFS partitions. + + +

You do not need to replace IRIX fsck program, because the +version that SGI distributes handles AFS volumes properly. +

Prepare for incorporating AFS into the kernel by performing the following +procedures. +
1. Mount the AFS CD-ROM for IRIX on the /cdrom directory. +For instructions on mounting CD-ROMs (either locally or remotely via NFS), see +your IRIX documentation. Then change directory as indicated. +
```
   
+   # cd  /cdrom/sgi_65/root.client
+   
+
```
  +
2. Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/init.d on IRIX +machines). Note the removal of the .rc extension as +you copy the script. +
```
   
+   # cp -p   usr/vice/etc/afs.rc  /etc/init.d/afs
+   
+
```
  +
3. Issue the uname -m command to determine the machine's CPU +board type. The IPxx value in the output must match +one of the supported CPU board types listed in the IBM AFS Release +Notes for the current version of AFS. +
```
   
+   # uname -m
+    
+
```
  +
+
Incorporate AFS into the kernel, either using the ml program or +by building AFS modifications into a static kernel. +
- To use the ml program: + + + + + + +
  1. Create the local /usr/vice/etc/sgiload directory to house the +AFS kernel library file. +
```
   
+   # mkdir /usr/vice/etc/sgiload
+   
+
```
    +
  2. Copy the appropriate AFS kernel library file to the +/usr/vice/etc/sgiload directory. The +IPxx portion of the library file name must match the value +previously returned by the uname -m command. Also choose the +file appropriate to whether the machine's kernel supports NFS server +functionality (NFS must be supported for the machine to act as an NFS/AFS +Translator). Single- and multiprocessor machines use the same library +file. +
    (You can choose to copy all of the kernel library files into the +/usr/vice/etc/sgiload directory, but they require a significant amount +of space.) +
    If the machine's kernel supports NFS server functionality: +
```
   
+   # cp -p  usr/vice/etc/sgiload/libafs.IPxx.o  /usr/vice/etc/sgiload   
+
```
    +
    If the machine's kernel does not support NFS server +functionality: +
```
   
+   # cp -p  usr/vice/etc/sgiload/libafs.IPxx.nonfs.o   \
+                   /usr/vice/etc/sgiload
+   
+
```
    +
  3. Issue the chkconfig command to activate the afsml +configuration variable. +
```
   
+   # /etc/chkconfig -f afsml on   
+
```
    +
    If the machine is to function as an NFS/AFS Translator and the kernel +supports NFS server functionality, activate the afsxnfs +variable. +
```
   
+   # /etc/chkconfig -f afsxnfs on
+   
+
```
    +
  4. Run the /etc/init.d/afs script to load AFS extensions +into the kernel. The script invokes the ml command, +automatically determining which kernel library file to use based on this +machine's CPU type and the activation state of the afsxnfs +variable. +
    You can ignore any error messages about the inability to start the BOS +Server or the Cache Manager or AFS client. +
```
   
+   # /etc/init.d/afs start
+   
+
```
    +
  5. Proceed to Step 3. +
  + +
- If you prefer to build a kernel, and the machine's hardware and +software configuration exactly matches another IRIX machine on which AFS is +already built into the kernel, you can copy the kernel from that machine to +this one. In general, however, it is better to build AFS modifications +into the kernel on each machine according to the following +instructions. +
  1. Copy the kernel initialization file afs.sm to the local +/var/sysgen/system directory, and the kernel master file +afs to the local /var/sysgen/master.d +directory. +
```
   
+   # cp -p  bin/afs.sm  /var/sysgen/system
+   
+   # cp -p  bin/afs  /var/sysgen/master.d
+   
+
```
    +
  2. Copy the appropriate AFS kernel library file to the local file +/var/sysgen/boot/afs.a; the IPxx +portion of the library file name must match the value previously returned by +the uname -m command. Also choose the file appropriate to +whether the machine's kernel supports NFS server functionality (NFS must +be supported for the machine to act as an NFS/AFS Translator). Single- +and multiprocessor machines use the same library file. +
    If the machine's kernel supports NFS server functionality: +
```
   
+   # cp -p   bin/libafs.IPxx.a   /var/sysgen/boot/afs.a   
+
```
    +
    If the machine's kernel does not support NFS server +functionality: +
```
   
+   # cp -p  bin/libafs.IPxx.nonfs.a  /var/sysgen/boot/afs.a
+   
+
```
    +
  3. Issue the chkconfig command to deactivate the afsml +configuration variable. +
```
   
+   # /etc/chkconfig -f afsml off   
+
```
    +
    If the machine is to function as an NFS/AFS Translator and the kernel +supports NFS server functionality, activate the afsxnfs +variable. +
```
    
+   # /etc/chkconfig -f afsxnfs on
+   
+
```
    +
  4. Copy the existing kernel file, /unix, to a safe +location. Compile the new kernel, which is created in the file +/unix.install. It overwrites the existing +/unix file when the machine reboots in the next step. +
```
   
+   # cp /unix /unix_noafs
+   
+   # autoconfig
+   
+
```
    +
  5. Reboot the machine to start using the new kernel, and login again as the +superuser root. +
```
   
+   # cd /
+         
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+
```
    +
  +
+ + + + +
Create a directory called /vicepxx for each +AFS server partition you are configuring (there must be at least one). +Repeat the command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Add a line with the following format to the file systems registry file, +/etc/fstab, for each partition (or logical volume created with the +XLV volume manager) to be mounted on one of the directories created in the +previous step. +
For an XFS partition or logical volume: +
```
   
+   /dev/dsk/disk  /vicepxx  xfs  rw,raw=/dev/rdsk/disk  0  0   
+
```
+
For an EFS partition: +
```
   
+   /dev/dsk/disk  /vicepxx  efs  rw,raw=/dev/rdsk/disk  0  0   
+
```
+
The following are examples of an entry for each file system type: +
```
   
+   /dev/dsk/dks0d2s6 /vicepa  xfs rw,raw=/dev/rdsk/dks0d2s6  0 0
+   /dev/dsk/dks0d3s1 /vicepb  efs rw,raw=/dev/rdsk/dks0d3s1  0 0
+   
+
```
+
Create a file system on each partition that is to be mounted on a +/vicepxx directory. The following commands are +probably appropriate, but consult the IRIX documentation for more +information. In both cases, raw_device is a raw device name +like /dev/rdsk/dks0d0s0 for a single disk partition or +/dev/rxlv/xlv0 for a logical volume. +
For XFS file systems, include the indicated options to configure the +partition or logical volume with inodes large enough to accommodate +AFS-specific information: +
```
   
+   # mkfs -t xfs -i size=512 -l size=4000b raw_device   
+
```
+
For EFS file systems: +
```
   
+   # mkfs -t efs raw_device
+   
+
```
+
Mount each partition by issuing either the mount -a command to +mount all partitions at once or the mount command to mount each +partition in turn. +
(Optional) If you have configured partitions or logical volumes +to use XFS, issue the following command to verify that the inodes are +configured properly (are large enough to accommodate AFS-specific +information). If the configuration is correct, the command returns no +output. Otherwise, it specifies the command to run in order to +configure each partition or logical volume properly. +
```
   
+   # /usr/afs/bin/xfs_size_check
+   
+
```
+
If the machine is to remain an AFS client, incorporate AFS into its +authentication system, following the instructions in Enabling AFS Login on IRIX Systems. +
Proceed to Starting Server Programs. +

Getting Started on Linux Systems

+ + +

Mount the AFS CD-ROM for Linux on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Linux documentation. Then change directory +as indicated. +
```
   
+   # cd  /cdrom/i386_linux22/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS kernel library files to the local +/usr/vice/etc/modload directory. The filenames for the +libraries have the format +libafs-version.o, where version +indicates the kernel build level. The string .mp in +the version indicates that the file is appropriate for machines +running a multiprocessor kernel. +
```
   
+   # cp -rp  modload  /usr/vice/etc
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/rc.d/init.d +on Linux machines). Note the removal of the .rc +extension as you copy the script. +
```
   
+   # cp -p   afs.rc  /etc/rc.d/init.d/afs 
+    
+
```
+
Run the AFS initialization script to load AFS extensions into the +kernel. You can ignore any error messages about the inability to start +the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/rc.d/init.d/afs  start
+   
+
```
+ + + + +
Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Add a line with the following format to the file systems registry file, +/etc/fstab, for each directory just created. The entry maps +the directory name to the disk partition to be mounted on it. +
```
   
+   /dev/disk  /vicepxx  ext2  defaults  0  2   
+
```
+
The following is an example for the first partition being +configured. +
```
   
+   /dev/sda8 /vicepa ext2 defaults 0 2
+   
+
```
+
Create a file system on each partition that is to be mounted at a +/vicepxx directory. The following command is +probably appropriate, but consult the Linux documentation for more +information. +
```
   
+   # mkfs -v /dev/disk
+   
+
```
+
Mount each partition by issuing either the mount -a command to +mount all partitions at once or the mount command to mount each +partition in turn. +
If the machine is to remain an AFS client, incorporate AFS into its +authentication system, following the instructions in Enabling AFS Login on Linux Systems. +
Proceed to Starting Server Programs. +

Getting Started on Solaris Systems

Begin by running the AFS initialization script to call the +modload program, which dynamically loads AFS modifications into the +kernel. Then configure partitions and replace the Solaris +fsck program with a version that correctly handles AFS +volumes. +

Mount the AFS CD-ROM for Solaris on the /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Solaris documentation. Then change +directory as indicated. +
```
   
+   # cd  /cdrom/sun4x_56/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/init.d on Solaris +machines). Note the removal of the .rc extension as +you copy the script. +
```
   
+   # cp -p  afs.rc  /etc/init.d/afs
+   
+
```
+
Copy the appropriate AFS kernel library file to the local file +/kernel/fs/afs. +
If the machine is running Solaris 2.6 or the 32-bit version of +Solaris 7, its kernel supports NFS server functionality, and the +nfsd process is running: +
```
   
+   # cp -p modload/libafs.o /kernel/fs/afs   
+
```
+
If the machine is running Solaris 2.6 or the 32-bit version of +Solaris 7, and its kernel does not support NFS server functionality or the +nfsd process is not running: +
```
   
+   # cp -p modload/libafs.nonfs.o /kernel/fs/afs   
+
```
+
If the machine is running the 64-bit version of Solaris 7, its kernel +supports NFS server functionality, and the nfsd process is +running: +
```
   
+   # cp -p modload/libafs64.o /kernel/fs/sparcv9/afs   
+
```
+
If the machine is running the 64-bit version of Solaris 7, and its +kernel does not support NFS server functionality or the nfsd +process is not running: +
```
   
+   # cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs
+   
+
```
+
Run the AFS initialization script to load AFS modifications into the +kernel. You can ignore any error messages about the inability to start +the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/init.d/afs start   
+
```
+
When an entry called afs does not already exist in the local +/etc/name_to_sysnum file, the script automatically creates it and +reboots the machine to start using the new version of the file. If this +happens, log in again as the superuser root after the reboot and +run the initialization script again. This time the required entry +exists in the /etc/name_to_sysnum file, and the modload +program runs. +
```
   
+   login: root
+   Password: root_password
+   
+   # /etc/init.d/afs start
+   
+
```
+ + + + +
Create the /usr/lib/fs/afs directory to house the AFS-modified +fsck program and related files. +
```
  
+   # mkdir /usr/lib/fs/afs
+   
+   # cd /usr/lib/fs/afs	
+  
+
```
+
Copy the vfsck binary to the newly created directory, changing +the name as you do so. +
```
   
+   # cp  /cdrom/sun4x_56/root.server/etc/vfsck  fsck
+  
+
```
+

Working in the /usr/lib/fs/afs directory, create the following +links to Solaris libraries: +

  
+   # ln -s /usr/lib/fs/ufs/clri	
+   # ln -s /usr/lib/fs/ufs/df
+   # ln -s /usr/lib/fs/ufs/edquota
+   # ln -s /usr/lib/fs/ufs/ff
+   # ln -s /usr/lib/fs/ufs/fsdb	
+   # ln -s /usr/lib/fs/ufs/fsirand
+   # ln -s /usr/lib/fs/ufs/fstyp
+   # ln -s /usr/lib/fs/ufs/labelit
+   # ln -s /usr/lib/fs/ufs/lockfs
+   # ln -s /usr/lib/fs/ufs/mkfs	
+   # ln -s /usr/lib/fs/ufs/mount
+   # ln -s /usr/lib/fs/ufs/ncheck
+   # ln -s /usr/lib/fs/ufs/newfs
+   # ln -s /usr/lib/fs/ufs/quot
+   # ln -s /usr/lib/fs/ufs/quota
+   # ln -s /usr/lib/fs/ufs/quotaoff
+   # ln -s /usr/lib/fs/ufs/quotaon
+   # ln -s /usr/lib/fs/ufs/repquota
+   # ln -s /usr/lib/fs/ufs/tunefs
+   # ln -s /usr/lib/fs/ufs/ufsdump
+   # ln -s /usr/lib/fs/ufs/ufsrestore
+   # ln -s /usr/lib/fs/ufs/volcopy
+   
+

Append the following line to the end of the file +/etc/dfs/fstypes. +
```
  
+   afs AFS Utilities
+  
+
```
+

Edit the /sbin/mountall file, making two changes. +

Add an entry for AFS to the case statement for option 2, so +that it reads as follows: +

  
+   case "$2" in
+   ufs)    foptions="-o p"
+           ;;
+   afs)    foptions="-o p"
+           ;;
+   s5)     foptions="-y -t /var/tmp/tmp$$ -D"
+           ;;
+   *)      foptions="-y"
+           ;;
+  
+

Edit the file so that all AFS and UFS partitions are checked in +parallel. Replace the following section of code: +

  
+   # For  fsck purposes, we make a distinction between ufs and
+   # other file systems
+   #
+   if [ "$fstype" = "ufs" ]; then
+        ufs_fscklist="$ufs_fscklist $fsckdev"
+        saveentry $fstype "$OPTIONS" $special $mountp
+        continue
+   fi  
+

with the following section of code: +

  
+   # For fsck purposes, we make a distinction between ufs/afs
+   # and other file systems.
+   #
+   if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
+        ufs_fscklist="$ufs_fscklist $fsckdev"
+        saveentry $fstype "$OPTIONS" $special $mountp
+        continue
+   fi
+  
+

+ + + + +

Create a directory called /vicepxx for each AFS server +partition you are configuring (there must be at least one). Repeat the +command for each partition. +
```
   
+   # mkdir /vicepxx
+   
+
```
+
Add a line with the following format to the file systems registry file, +/etc/vfstab, for each partition to be mounted on a directory +created in the previous step. Note the value afs in the +fourth field, which tells Solaris to use the AFS-modified fsck +program on this partition. +
```
   
+   /dev/dsk/disk   /dev/rdsk/disk   /vicepxx   afs   boot_order  yes  
+
```
+
The following is an example for the first partition being +configured. +
```
  
+   /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
+  
+
```
+
Create a file system on each partition that is to be mounted at a +/vicepxx directory. The following command is +probably appropriate, but consult the Solaris documentation for more +information. +
```
  
+   # newfs -v /dev/rdsk/disk
+  
+
```
+
Issue the mountall command to mount all partitions at +once. +
If the machine is to remain an AFS client, incorporate AFS into its +authentication system, following the instructions in Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems. +
Proceed to Starting Server Programs. +

+ + +

Starting Server Programs

In this section you initialize the BOS Server, the Update +Server, the controller process for NTPD, and the fs process. +You begin by copying the necessary server files to the local disk. +

Copy file server binaries to the local /usr/afs/bin +directory. +
- On a machine of an existing system type, you can either load files from +the AFS CD-ROM or use a remote file transfer protocol to copy files from an +existing server machine of the same system type. To load from the +CD-ROM, see the instructions just following for a machine of a new system +type. If using a remote file transfer protocol, copy the complete +contents of the existing server machine's /usr/afs/bin +directory. +
- On a machine of a new system type, you must use the following instructions +to copy files from the AFS CD-ROM. +
  1. On the local /cdrom directory, mount the AFS CD-ROM for this +machine's system type, if it is not already. For instructions on +mounting CD-ROMs (either locally or remotely via NFS), consult the operating +system documentation. +
  2. Copy files from the CD-ROM to the local /usr/afs +directory. +
```
   
+   # cd /cdrom/sysname/root.server/usr/afs
+   
+   # cp -rp  *  /usr/afs
+   
+
```
    +
  +
+ + + + + + + + + + + + +
Copy the contents of the /usr/afs/etc directory from an +existing file server machine, using a remote file transfer protocol such as +ftp or NFS. If you use a system control machine, it is best +to copy the contents of its /usr/afs/etc directory. If you +choose not to run a system control machine, copy the directory's contents +from any existing file server machine. + + + + + + +
Change to the /usr/afs/bin directory and start the BOS Server +(bosserver process). Include the -noauth flag to +prevent the AFS processes from performing authorization checking. This +is a grave compromise of security; finish the remaining instructions in +this section in an uninterrupted pass. +
```
    
+   # cd /usr/afs/bin
+    
+   # ./bosserver -noauth &
+    
+
```
+ + + + + + +
If you run a system control machine, create the +upclientetc process as an instance of the client portion of the +Update Server. It accepts updates of the common configuration files +stored in the system control machine's /usr/afs/etc directory +from the upserver process (server portion of the Update Server) +running on that machine. The cell's first file server machine was +installed as the system control machine in Starting the Server Portion of the Update Server. (If you do not run a system control machine, you +must update the contents of the /usr/afs/etc directory on each file +server machine, using the appropriate bos commands.) +
By default, the Update Server performs updates every 300 seconds (five +minutes). Use the -t argument to specify a different number +of seconds. For the machine name argument, substitute the +name of the machine you are installing. The command appears on multiple +lines here only for legibility reasons. +
```
      
+   # ./bos create  <machine name> upclientetc simple  \ 
+         "/usr/afs/bin/upclient  <system control machine>  \  
+         [-t  <time>]  /usr/afs/etc" -cell  <cell name>  -noauth
+   
+
```
+ + + +
Create an instance of the Update Server to handle distribution +of the file server binaries stored in the /usr/afs/bin +directory. +
- If this is the first file server machine of its AFS system type, create +the upserver process as an instance of the server portion of the +Update Server. It distributes its copy of the file server process +binaries to the other file server machines of this system type that you +install in future. Creating this process makes this machine the binary +distribution machine for its type. +
```
   
+   # ./bos create  <machine name> upserver  simple  \ 
+         "/usr/afs/bin/upserver -clear /usr/afs/bin"   \
+         -cell <cell name>  -noauth
+    
+
```
  +
- If this machine is an existing system type, create the +upclientbin process as an instance of the client portion of the +Update Server. It accepts updates of the AFS binaries from the +upserver process running on the binary distribution machine for its +system type. For distribution to work properly, the upserver +process must already by running on that machine. +
  Use the -clear argument to specify that the +upclientbin process requests unencrypted transfer of the binaries +in the /usr/afs/bin directory. Binaries are not sensitive +and encrypting them is time-consuming. +
  By default, the Update Server performs updates every 300 seconds (five +minutes). Use the -t argument to specify an different number +of seconds. +
```
   
+   # ./bos create  <machine name> upclientbin simple  \ 
+        "/usr/afs/bin/upclient <binary distribution machine>   \
+        [-t <time>] -clear /usr/afs/bin" -cell <cell name>  -noauth
+   
+
```
  +
+ + + + +

Start the runntp process, which configures the Network Time +Protocol Daemon (NTPD) to choose a database server machine chosen randomly +from the local /usr/afs/etc/CellServDB file as its time +source. In the standard configuration, the first database server +machine installed in your cell refers to a time source outside the cell, and +serves as the basis for clock synchronization on all server machines. +

   
+   # ./bos create  <machine name> runntp simple  \ 
+         /usr/afs/bin/runntp -cell <cell name>  -noauth
+

Note:

Do not run the runntp process if NTPD or another time +synchronization protocol is already running on the machine. Some +versions of some operating systems run a time synchronization program by +default, as detailed in the IBM AFS Release Notes. +

Attempting to run multiple instances of the NTPD causes an error. +Running NTPD together with another time synchronization protocol is +unnecessary and can cause instability in the clock setting. +

+ + + + + + + + + + +

Start the fs process, which binds together the File Server, +Volume Server, and Salvager. +

   
+   # ./bos create  <machine name> fs fs   \ 
+         /usr/afs/bin/fileserver /usr/afs/bin/volserver  \ 
+         /usr/afs/bin/salvager -cell <cell name>  -noauth
+   
+

+ + +

Installing Client Functionality

If you want this machine to be a client as well as a server, +follow the instructions in this section. Otherwise, skip to Completing the Installation. +

Begin by loading the necessary client files to the local disk. Then +create the necessary configuration files and start the Cache Manager. +For more detailed explanation of the procedures involved, see the +corresponding instructions in Installing the First AFS Machine (in the sections following Overview: Installing Client Functionality). +

If another AFS machine of this machine's system type exists, the AFS +binaries are probably already accessible in your AFS filespace (the +conventional location is +/afs/cellname/sysname/usr/afsws). +If not, or if this is the first AFS machine of its type, copy the AFS binaries +for this system type into an AFS volume by following the instructions in Storing AFS Binaries in AFS. Because this machine is not yet an AFS client, you +must perform the procedure on an existing AFS machine. However, +remember to perform the final step (linking the local directory +/usr/afsws to the appropriate location in the AFS file tree) on +this machine itself. If you also want to create AFS volumes to house +UNIX system binaries for the new system type, see Storing System Binaries in AFS. + + + +

Copy client binaries and files to the local disk. +
- On a machine of an existing system type, you can either load files from +the AFS CD-ROM or use a remote file transfer protocol to copy files from an +existing server machine of the same system type. To load from the +CD-ROM, see the instructions just following for a machine of a new system +type. If using a remote file transfer protocol, copy the complete +contents of the existing client machine's /usr/vice/etc +directory. +
- On a machine of a new system type, you must use the following instructions +to copy files from the AFS CD-ROM. +
  1. On the local /cdrom directory, mount the AFS CD-ROM for this +machine's system type, if it is not already. For instructions on +mounting CD-ROMs (either locally or remotely via NFS), consult the operating +system documentation. +
  2. Copy files to the local /usr/vice/etc directory. +
    This step places a copy of the AFS initialization script (and related +files, if applicable) into the /usr/vice/etc directory. In +the preceding instructions for incorporating AFS into the kernel, you copied +the script directly to the operating system's conventional location for +initialization files. When you incorporate AFS into the machine's +startup sequence in a later step, you can choose to link the two files. +
    On some system types that use a dynamic kernel loader program, you +previously copied AFS library files into a subdirectory of the +/usr/vice/etc directory. On other system types, you copied +the appropriate AFS library file directly to the directory where the operating +system accesses it. The following commands do not copy or recopy the +AFS library files into the /usr/vice/etc directory, because on some +system types the library files consume a large amount of space. If you +want to copy them, add the -r flag to the first cp +command and skip the second cp command. +
```
   
+   # cd /cdrom/sysname/root.client/usr/vice/etc
+   
+   # cp -p  *  /usr/vice/etc
+  
+   # cp -rp  C  /usr/vice/etc
+   
+
```
    +
  +
+ + + + + + +
Change to the /usr/vice/etc directory and create the +ThisCell file as a copy of the /usr/afs/etc/ThisCell +file. You must first remove the symbolic link to the +/usr/afs/etc/ThisCell file that the BOS Server created +automatically in Starting Server Programs. +
```
   
+   # cd  /usr/vice/etc
+   
+   # rm  ThisCell
+ 
+   # cp  /usr/afs/etc/ThisCell  ThisCell
+      
+
```
+
Remove the symbolic link to the /usr/afs/etc/CellServDB +file. +
```
   
+   # rm  CellServDB
+   
+
```
+ + + +
Create the /usr/vice/etc/CellServDB file. Use a network +file transfer program such as ftp or NFS to copy it from one of the +following sources, which are listed in decreasing order of preference: +
- Your cell's central CellServDB source file (the +conventional location is +/afs/cellname/common/etc/CellServDB) +
- The global CellServDB file maintained by the AFS Product +Support group +
- An existing client machine in your cell +
- The CellServDB.sample file included in the +sysname/root.client/usr/vice/etc directory of each +AFS CD-ROM; add an entry for the local cell by following the instructions +in Creating the Client CellServDB File +
+ + + + +
Create the cacheinfo file for either a disk cache or a memory +cache. For a discussion of the appropriate values to record in the +file, see Configuring the Cache. +
To configure a disk cache, issue the following commands. If you are +devoting a partition exclusively to caching, as recommended, you must also +configure it, make a file system on it, and mount it at the directory created +in this step. +
```
   
+   # mkdir /usr/vice/cache
+   
+   # echo "/afs:/usr/vice/cache:#blocks" > cacheinfo   
+
```
+
To configure a memory cache: +
```
    
+   # echo "/afs:/usr/vice/cache:#blocks" > cacheinfo
+   
+
```
+ + + + + + +
Create the local directory on which to mount the AFS filespace, by +convention /afs. If the directory already exists, verify +that it is empty. +
```
   
+   # mkdir /afs
+   
+
```
+
On AIX systems, add the following line to the /etc/vfs +file. It enables AIX to unmount AFS correctly during shutdown. +
```
   
+   afs     4     none     none
+   
+
```
+
On Linux systems, copy the afsd options file from the +/usr/vice/etc directory to the /etc/sysconfig directory, +removing the .conf extension as you do so. +
```
   
+   # cp /usr/vice/etc/afs.conf /etc/sysconfig/afs
+   
+
```
+
Edit the machine's AFS initialization script or afsd +options file to set appropriate values for afsd command +parameters. The script resides in the indicated location on each system +type: +
- On AIX systems, /etc/rc.afs +
- On Digital UNIX systems, /sbin/init.d/afs +
- On HP-UX systems, /sbin/init.d/afs +
- On IRIX systems, /etc/init.d/afs +
- On Linux systems, /etc/sysconfig/afs (the afsd +options file) +
- On Solaris systems, /etc/init.d/afs +
+
Use one of the methods described in Configuring the Cache Manager to add the following flags to the afsd command +line. If you intend for the machine to remain an AFS client, also set +any performance-related arguments you wish. +
- Add the -nosettime flag, because this is a file server machine +that is also a client. +
- Add the -memcache flag if the machine is to use a memory +cache. +
- Add the -verbose flag to display a trace of the Cache +Manager's initialization on the standard output stream. +
+
If appropriate, follow the instructions in Storing AFS Binaries in AFS to copy the AFS binaries for this system type into an AFS +volume. See the introduction to this section for further +discussion. +

Completing the Installation

At this point you run the machine's AFS initialization +script to verify that it correctly loads AFS modifications into the kernel and +starts the BOS Server, which starts the other server processes. If you +have installed client files, the script also starts the Cache Manager. +If the script works correctly, perform the steps that incorporate it into the +machine's startup and shutdown sequence. If there are problems +during the initialization, attempt to resolve them. The AFS Product +Support group can provide assistance if necessary. +

If the machine is configured as a client using a disk cache, it can take a +while for the afsd program to create all of the +Vn files in the cache directory. Messages on the +console trace the initialization process. +

Issue the bos shutdown command to shut down the AFS server +processes other than the BOS Server. Include the -wait flag +to delay return of the command shell prompt until all processes shut down +completely. +
```
      
+   # /usr/afs/bin/bos shutdown <machine name> -wait
+   
+
```
+
Issue the ps command to learn the BOS Server's process ID +number (PID), and then the kill command to stop the +bosserver process. +
```
   
+   # ps appropriate_ps_options | grep bosserver
+   
+   # kill bosserver_PID
+   
+
```
+ + + + + + +
Run the AFS initialization script by issuing the appropriate commands for +this system type. +
On AIX systems: +
1. Reboot the machine and log in again as the local superuser +root. +
```
   
+   # cd /
+   
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+
```
  +
2. Run the AFS initialization script. +
```
   
+   # /etc/rc.afs
+   
+
```
  +
3. Edit the AIX initialization file, /etc/inittab, adding the +following line to invoke the AFS initialization script. Place it just +after the line that starts NFS daemons. +
```
   
+   rcafs:2:wait:/etc/rc.afs > /dev/console 2>&1 # Start AFS services
+   
+
```
  +
4. (Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc directories. +If you want to avoid potential confusion by guaranteeing that they are always +the same, create a link between them. You can always retrieve the +original script from the AFS CD-ROM if necessary. +
```
   
+   # cd  /usr/vice/etc
+   
+   # rm  rc.afs
+  
+   # ln -s  /etc/rc.afs
+   
+
```
  +
5. Proceed to Step 4. +
+ +
On Digital UNIX systems: +
1. Run the AFS initialization script. +
```
   
+   # /sbin/init.d/afs  start
+   
+
```
  +
2. Change to the /sbin/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the Digital UNIX startup and shutdown +sequence. +
```
   
+   # cd  /sbin/init.d
+   
+   # ln -s  ../init.d/afs  /sbin/rc3.d/S67afs
+   
+   # ln -s  ../init.d/afs  /sbin/rc0.d/K66afs
+   
+
```
  +
3. (Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /sbin/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /sbin/init.d/afs  afs.rc
+   
+
```
  +
4. Proceed to Step 4. +
+ +
On HP-UX systems: +
1. Run the AFS initialization script. +
```
   
+   # /sbin/init.d/afs  start
+   
+
```
  +
2. Change to the /sbin/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the HP-UX startup and shutdown sequence. +
```
   
+   # cd /sbin/init.d
+   
+   # ln -s ../init.d/afs /sbin/rc2.d/S460afs
+  
+   # ln -s ../init.d/afs /sbin/rc2.d/K800afs
+   
+
```
  +
3. (Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /sbin/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /sbin/init.d/afs  afs.rc
+   
+
```
  +
4. Proceed to Step 4. +
+ + + + + + + +
On IRIX systems: +
1. If you have configured the machine to use the ml dynamic loader +program, reboot the machine and log in again as the local superuser +root. +
```
   
+   # cd /
+        
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+
```
  +
2. Issue the chkconfig command to activate the +afsserver configuration variable. +
```
   
+   # /etc/chkconfig -f afsserver on   
+
```
  +
  If you have configured this machine as an AFS client and want to it remain +one, also issue the chkconfig command to activate the +afsclient configuration variable. +
```
   
+   # /etc/chkconfig -f afsclient on 
+   
+
```
  +
3. Run the AFS initialization script. +
```
   
+   # /etc/init.d/afs  start
+   
+
```
  +
4. Change to the /etc/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the IRIX startup and shutdown sequence. +
```
   
+   # cd /etc/init.d
+   
+   # ln -s ../init.d/afs /etc/rc2.d/S35afs
+  
+   # ln -s ../init.d/afs /etc/rc0.d/K35afs
+   
+
```
  +
5. (Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /etc/init.d/afs  afs.rc
+   
+
```
  +
6. Proceed to Step 4. +
+ +
On Linux systems: +
1. Reboot the machine and log in again as the local superuser +root. +
```
  
+   # cd /
+         
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+
```
  +
2. Run the AFS initialization script. +
```
   
+   # /etc/rc.d/init.d/afs  start
+   
+
```
  +
3. Issue the chkconfig command to activate the afs +configuration variable. Based on the instruction in the AFS +initialization file that begins with the string #chkconfig, the +command automatically creates the symbolic links that incorporate the script +into the Linux startup and shutdown sequence. +
```
   
+   # /sbin/chkconfig  --add afs
+   
+
```
  +
4. (Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and +/etc/rc.d/init.d directories, and copies of the +afsd options file in both the /usr/vice/etc and +/etc/sysconfig directories. If you want to avoid potential +confusion by guaranteeing that the two copies of each file are always the +same, create a link between them. You can always retrieve the original +script or options file from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc afs.conf
+    
+   # ln -s  /etc/rc.d/init.d/afs  afs.rc
+   
+   # ln -s  /etc/sysconfig/afs  afs.conf
+   
+
```
  +
5. Proceed to Step 4. +
+ +
On Solaris systems: +
1. Reboot the machine and log in again as the local superuser +root. +
```
   
+   # cd /
+      
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+
```
  +
2. Run the AFS initialization script. +
```
   
+   # /etc/init.d/afs  start
+   
+
```
  +
3. Change to the /etc/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the Solaris startup and shutdown sequence. +
```
   
+   # cd /etc/init.d
+  
+   # ln -s ../init.d/afs /etc/rc3.d/S99afs
+  
+   # ln -s ../init.d/afs /etc/rc0.d/K66afs
+   
+
```
  +
4. (Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /etc/init.d/afs  afs.rc
+   
+
```
  +
+
Verify that /usr/afs and its subdirectories on the +new file server machine meet the ownership and mode bit requirements outlined +in Protecting Sensitive AFS Directories. If necessary, use the chmod command to +correct the mode bits. +
To configure this machine as a database server machine, proceed to Installing Database Server Functionality. +

+ + +

Installing Database Server Functionality

This section explains how to install database server +functionality. Database server machines have two defining +characteristics. First, they run the Authentication Server, Protection +Server, and Volume Location (VL) Server processes. They also run the +Backup Server if the cell uses the AFS Backup System, as is assumed in these +instructions. Second, they appear in the CellServDB file of +every machine in the cell (and of client machines in foreign cells, if they +are to access files in this cell). +

Note the following requirements for database server machines. +

In the conventional configuration, database server machines also serve as +file server machines (run the File Server, Volume Server and Salvager +processes). If you choose not to run file server functionality on a +database server machine, then the kernel does not have to incorporate AFS +modifications, but the local /usr/afs directory must house most of +the standard files and subdirectories. In particular, the +/usr/afs/etc/KeyFile file must contain the same keys as all other +server machines in the cell. If you run a system control machine, run +the upclientetc process on every database server machine other than +the system control machine; if you do not run a system control machine, +use the bos addkey command as instructed in the chapter in the +IBM AFS Administration Guide about maintaining server encryption +keys. +
The instructions in this section assume that the machine on which you are +installing database server functionality is already a file server +machine. Contact the AFS Product Support group to learn how to install +database server functionality on a non-file server machine. +
During the installation of database server functionality, you must restart +all of the database server machines to force the election of a new Ubik +coordinator (synchronization site) for each database server process. +This can cause a system outage, which usually lasts less than 5 +minutes. +
Updating the kernel memory list of database server machines on each client +machine is generally the most time-consuming part of installing a new database +server machine. It is, however, crucial for correct functioning in your +cell. Incorrect knowledge of your cell's database server machines +can prevent your users from authenticating, accessing files, and issuing AFS +commands. +
You update a client's kernel memory list by changing the +/usr/vice/etc/CellServDB file and then either rebooting or issuing +the fs newcell command. For instructions, see the chapter in +the IBM AFS Administration Guide about administering client +machines. +
The point at which you update your clients' knowledge of database +server machines depends on which of the database server machines has the +lowest IP address. The following instructions indicate the appropriate +place to update your client machines in either case. +
- If the new database server machine has a lower IP address than any +existing database server machine, update the CellServDB file on +every client machine before restarting the database server processes. +If you do not, users can become unable to update (write to) any of the AFS +databases. This is because the machine with the lowest IP address is +usually elected as the Ubik coordinator, and only the Coordinator accepts +database writes. On client machines that do not have the new list of +database server machines, the Cache Manager cannot locate the new +coordinator. (Be aware that if clients contact the new coordinator +before it is actually in service, they experience a timeout before contacting +another database server machine. This is a minor, and temporary, +problem compared to being unable to write to the database.) +
- If the new database server machine does not have the lowest IP address of +any database server machine, then it is better to update clients after +restarting the database server processes. Client machines do not start +using the new database server machine until you update their kernel memory +list, but that does not usually cause timeouts or update problems (because the +new machine is not likely to become the coordinator). +
+

+ +

Summary of Procedures

To install a database server machine, perform the following +procedures. +

Install the bos suite of commands locally, as a precaution +
Add the new machine to the /usr/afs/etc/CellServDB file on +existing file server machines +
Update your cell's central CellServDB source file and the +file you make available to foreign cells +
Update every client machine's /usr/vice/etc/CellServDB +file and kernel memory list of database server machines +
Start the database server processes (Authentication Server, Backup Server, +Protection Server, and Volume Location Server) +
Restart the database server processes on every database server machine +
Notify the AFS Product Support group that you have installed a new +database server machine +

+ + + +

Instructions

Note:

It is assumed that your PATH environment variable includes the directory +that houses the AFS command binaries. If not, you possibly need to +precede the command names with the appropriate pathname. +

You can perform the following instructions on either a server or client +machine. Login as an AFS administrator who is listed in the +/usr/afs/etc/UserList file on all server machines. +
```
   
+   % klog admin_user
+   Password: admin_password
+   
+
```
+
If you are working on a client machine configured in the conventional +manner, the bos command suite resides in the +/usr/afsws/bin directory, a symbolic link to an AFS +directory. An error during installation can potentially block access to +AFS, in which case it is helpful to have a copy of the bos binary +on the local disk. This step is not necessary if you are working on a +server machine, where the binary resides in the local /usr/afs/bin +directory. +
```
   
+   % cp  /usr/afsws/bin/bos   /tmp
+   
+
```
+ + + + + +

Issue the bos addhost command to add the new +database server machine to the /usr/afs/etc/CellServDB file on +existing server machines (as well as the new database server machine +itself). +

Substitute the new database server machine's fully-qualified hostname +for the host name argument. If you run a system control +machine, substitute its fully-qualified hostname for the +machine name argument. If you do not run a system control +machine, repeat the bos addhost command once for each server +machine in your cell (including the new database server machine itself), by +substituting each one's fully-qualified hostname for the +machine name argument in turn. +

   
+   % bos addhost <machine name>  <host name>   
+

If you run a system control machine, wait for the Update Server to +distribute the new CellServDB file, which takes up to five minutes +by default. If you are issuing individual bos addhost +commands, attempt to issue all of them within five minutes. +
Note: It is best to maintain a one-to-one mapping between hostnames and IP +addresses on a multihomed database server machine (the conventional +configuration for any AFS machine). The BOS Server uses the +gethostbyname( ) routine to obtain the IP address +associated with the host name argument. If there is more than +one address, the BOS Server records in the CellServDB entry the one +that appears first in the list of addresses returned by the routine. +The routine possibly returns addresses in a different order on different +machines, which can create inconsistency. +
+

(Optional) Issue the bos listhosts command on each +server machine to verify that the new database server machine appears in its +CellServDB file. +
```
   
+   % bos listhosts <machine name>
+   
+
```
+
Add the new database server machine to your cell's central +CellServDB source file, if you use one. The standard +location is +/afs/cellname/common/etc/CellServDB. +
If you are willing to make your cell accessible to users in foreign cells, +add the new database server machine to the file that lists your cell's +database server machines. The conventional location is +/afs/cellname/service/etc/CellServDB.local. + + + +
If this machine's IP address is lower than any existing +database server machine's, update every client machine's +/usr/vice/etc/CellServDB file and kernel memory list to include +this machine. (If this machine's IP address is not the lowest, it +is acceptable to wait until Step 12.) +
There are several ways to update the CellServDB file on client +machines, as detailed in the chapter of the IBM AFS Administration +Guide about administering client machines. One option is to copy +over the central update source (which you updated in Step 5), with or without using the package +program. To update the machine's kernel memory list, you can +either reboot after changing the CellServDB file or issue the +fs newcell command. + + + + + +

Start the Authentication Server (the kaserver +process). +

   
+   % bos create <machine name> kaserver simple /usr/afs/bin/kaserver
+   
+

+ + +

Start the Backup Server (the buserver +process). You must perform other configuration procedures before +actually using the AFS Backup System, as detailed in the IBM AFS +Administration Guide. +
```
   
+   % bos create <machine name> buserver simple /usr/afs/bin/buserver
+   
+
```
+ + +

Start the Protection Server (the ptserver +process). +

   
+   % bos create <machine name> ptserver simple /usr/afs/bin/ptserver
+    
+

+ + +

Start the Volume Location (VL) Server (the vlserver +process). +

      
+   % bos create <machine name> vlserver simple /usr/afs/bin/vlserver
+   
+

+ + + + +

Issue the bos restart command on every database +server machine in the cell, including the new machine. The command +restarts the Authentication, Backup, Protection, and VL Servers, which forces +an election of a new Ubik coordinator for each process. The new machine +votes in the election and is considered as a potential new coordinator. +
+
A cell-wide service outage is possible during the election of a new +coordinator for the VL Server, but it normally lasts less than five +minutes. Such an outage is particularly likely if you are installing +your cell's second database server machine. Messages tracing the +progress of the election appear on the console. +
Repeat this command on each of your cell's database server machines in +quick succession. Begin with the machine with the lowest IP +address. +
```
   
+   %  bos restart <machine name> kaserver buserver ptserver vlserver    
+
```
+
If an error occurs, restart all server processes on the database server +machines again by using one of the following methods: +
- Issue the bos restart command with the -bosserver +flag for each database server machine +
- Reboot each database server machine, either using the bos exec +command or at its console +
+
If you did not update the CellServDB file on client +machines in Step 6, do so now. +
Send the new database server machine's name and IP address +to the AFS Product Support group. +
If you wish to participate in the AFS global name space, your cell's +entry appear in a CellServDB file that the AFS Product Support +group makes available to all AFS sites. Otherwise, they list your cell +in a private file that they do not share with other AFS sites. +

+ + + + +

Removing Database Server Functionality

Removing database server machine functionality is nearly the +reverse of installing it. +

Summary of Procedures

To decommission a database server machine, perform the following +procedures. +

Install the bos suite of commands locally, as a precaution +
Notify the AFS Product Support group that you are decommissioning a +database server machine +
Update your cell's central CellServDB source file and the +file you make available to foreign cells +
Update every client machine's /usr/vice/etc/CellServDB +file and kernel memory list of database server machines +
Remove the machine from the /usr/afs/etc/CellServDB file on +file server machines +
Stop the database server processes and remove them from the +/usr/afs/local/BosConfig file if desired +
Restart the database server processes on the remaining database server +machines +

Instructions

Note:

You can perform the following instructions on either a server or client +machine. Login as an AFS administrator who is listed in the +/usr/afs/etc/UserList file on all server machines. +
```
   
+   % klog admin_user
+   Password: admin_password
+   
+
```
+
If you are working on a client machine configured in the conventional +manner, the bos command suite resides in the +/usr/afsws/bin directory, a symbolic link to an AFS +directory. An error during installation can potentially block access to +AFS, in which case it is helpful to have a copy of the bos binary +on the local disk. This step is not necessary if you are working on a +server machine, where the binary resides in the local /usr/afs/bin +directory. +
```
      
+   % cp  /usr/afsws/bin/bos   /tmp
+   
+
```
+
Send the revised list of your cell's database server +machines to the AFS Product Support group. +
This step is particularly important if your cell is included in the global +CellServDB file. If the administrators in foreign cells do +not learn about the change in your cell, they cannot update the +CellServDB file on their client machines. Users in foreign +cells continue to send database requests to the decommissioned machine, which +creates needless network traffic and activity on the machine. Also, the +users experience time-out delays while their request is forwarded to a valid +database server machine. +
Remove the decommissioned machine from your cell's central +CellServDB source file, if you use one. The conventional +location is +/afs/cellname/common/etc/CellServDB. +
If you maintain a file that users in foreign cells can access to learn +about your cell's database server machines, update it also. The +conventional location is +/afs/cellname/service/etc/CellServDB.local. + + + + +
Update every client machine's +/usr/vice/etc/CellServDB file and kernel memory list to exclude +this machine. Altering the CellServDB file and kernel memory +list before stopping the actual database server processes avoids possible +time-out delays that result when users send requests to a decommissioned +database server machine that is still listed in the file. +
There are several ways to update the CellServDB file on client +machines, as detailed in the chapter of the IBM AFS Administration +Guide about administering client machines. One option is to copy +over the central update source (which you updated in Step 5), with or without using the package +program. To update the machine's kernel memory list, you can +either reboot after changing the CellServDB file or issue the +fs newcell command. + + + + +
Issue the bos removehost command to remove the +decommissioned database server machine from the +/usr/afs/etc/CellServDB file on server machines. +
Substitute the decommissioned database server machine's +fully-qualified hostname for the host name argument. If you +run a system control machine, substitute its fully-qualified hostname for the +machine name argument. If you do not run a system control +machine, repeat the bos removehost command once for each server +machine in your cell (including the decommissioned database server machine +itself), by substituting each one's fully-qualified hostname for the +machine name argument in turn. +
```
   
+   % bos removehost <machine name>  <host name>   
+
```
+
If you run a system control machine, wait for the Update Server to +distribute the new CellServDB file, which takes up to five minutes +by default. If issuing individual bos removehost commands, +attempt to issue all of them within five minutes. +
(Optional) Issue the bos listhosts command on each +server machine to verify that the decommissioned database server machine no +longer appears in its CellServDB file. +
```
   
+   % bos listhosts <machine name>
+   
+
```
+ + + + + + + +
Issue the bos stop command to stop the database +server processes on the machine, by substituting its fully-qualified hostname +for the machine name argument. The command changes each +process's status in the /usr/afs/local/BosConfig file to +NotRun, but does not remove its entry from the file. +
```
   
+   % bos stop <machine name> kaserver buserver ptserver vlserver
+    
+
```
+ + + + + +
(Optional) Issue the bos delete command +to remove the entries for database server processes from the +BosConfig file. This step is unnecessary if you plan to +restart the database server functionality on this machine in future. +
```
   
+   % bos delete <machine name> kaserver buserver ptserver vlserver
+    
+
```
+ + + + +
Issue the bos restart command on every database +server machine in the cell, to restart the Authentication, Backup, Protection, +and VL Servers. This forces the election of a Ubik coordinator for each +process, ensuring that the remaining database server processes recognize that +the machine is no longer a database server. +
A cell-wide service outage is possible during the election of a new +coordinator for the VL Server, but it normally lasts less than five +minutes. Messages tracing the progress of the election appear on the +console. +
Repeat this command on each of your cell's database server machines in +quick succession. Begin with the machine with the lowest IP +address. +
```
   
+   %  bos restart <machine name> kaserver buserver ptserver vlserver    
+
```
+
If an error occurs, restart all server processes on the database server +machines again by using one of the following methods: +
- Issue the bos restart command with the -bosserver +flag for each database server machine +
- Reboot each database server machine, either using the bos exec +command or at its console +
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartUnix/auqbg007.htm b/doc/html/QuickStartUnix/auqbg007.htm new file mode 100644 index 0000000..1a6aef7 --- /dev/null +++ b/doc/html/QuickStartUnix/auqbg007.htm @@ -0,0 +1,2223 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

+ + +

Installing Additional Client Machines

This chapter describes how to install AFS client machines +after you have installed the first AFS machine. Some parts of the +installation differ depending on whether or not the new client is of the same +AFS system type (uses the same AFS binaries) as a previously installed client +machine. + +

Summary of Procedures

Incorporate AFS into the machine's kernel +
Define the machine's cell membership +
Define cache location and size +
Create the /usr/vice/etc/CellServDB file, which determines +which foreign cells the client can access in addition to the local cell +
Create the /afs directory and start the Cache Manager +
Create and mount volumes for housing AFS client binaries (necessary only +for clients of a new system type) +
Create a link from the local /usr/afsws directory to the AFS +directory housing the AFS client binaries +
Modify the machine's authentication system to enable AFS users to +obtain tokens at login +

+ + + + + + + +

Creating AFS Directories on the Local Disk

Create the /usr/vice/etc directory on the local +disk, to house client binaries and configuration files. Subsequent +instructions copy files from the AFS CD-ROM into them. Create the +/cdrom directory as a mount point for the CD-ROM, if it does not +already exist. +

      
+   # mkdir /usr/vice
+      
+   # mkdir /usr/vice/etc
+   
+   # mkdir /cdrom
+   
+

Performing Platform-Specific Procedures

Every AFS client machine's kernel must incorporate AFS +modifications. Some system types use a dynamic kernel loader program, +whereas on other system types you build AFS modifications into a static +kernel. Some system types support both methods. +

Also modify the machine's authentication system so that users obtain +an AFS token as they log into the local file system. Using AFS is +simpler and more convenient for your users if you make the modifications on +all client machines. Otherwise, users must perform a two-step login +procedure (login to the local file system and then issue the klog +command). For further discussion of AFS authentication, see the chapter +in the IBM AFS Administration Guide about cell configuration and +administration issues. +

For convenience, the following sections group the two procedures by system +type. Proceed to the appropriate section. +

Getting Started on AIX Systems +
Getting Started on Digital UNIX Systems +
Getting Started on HP-UX Systems +
Getting Started on IRIX Systems +
Getting Started on Linux Systems +
Getting Started on Solaris Systems +

+ + + + + + + + + +

Getting Started on AIX Systems

In this section you load AFS into the AIX kernel. +Then incorporate AFS modifications into the machine's secondary +authentication system, if you wish to enable AFS login. +

Loading AFS into the AIX Kernel

The AIX kernel extension facility is the dynamic kernel loader provided +by IBM Corporation. AIX does not support incorporation of AFS +modifications during a kernel build. +

After editing the script, you run it to incorporate AFS into the +kernel. In a later section you verify that the script correctly +initializes the Cache Manager, then configure the AIX inittab file +so that the script runs automatically at reboot. +

Mount the AFS CD-ROM for AIX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your AIX documentation. Then change directory as +indicated. +
```
   
+   # cd  /cdrom/rs_aix42/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS kernel library files to the local +/usr/vice/etc/dkload directory, and the AFS initialization script +to the /etc directory. +
```
   
+   # cp -rp  dkload  /usr/vice/etc
+   
+   # cp -p  rc.afs  /etc/rc.afs
+    
+
```
+
Edit the /etc/rc.afs script, setting the NFS +variable as indicated. +
If the machine is not to function as an NFS/AFS Translator, set the +NFS variable as follows. +
```
      
+   NFS=$NFS_NONE
+
```
+
If the machine is to function as an NFS/AFS Translator and is running AIX +4.2.1 or higher, set the NFS variable as +follows. Note that NFS must already be loaded into the kernel, which +happens automatically on systems running AIX 4.1.1 and later, as +long as the file /etc/exports exists. +
```
   
+   NFS=$NFS_IAUTH
+   
+
```
+
Invoke the /etc/rc.afs script to load AFS modifications +into the kernel. You can ignore any error messages about the inability +to start the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/rc.afs
+   
+
```
+

Enabling AFS Login on AIX Systems

Now incorporate AFS into the AIX secondary authentication +system. +

Issue the ls command to verify that the +afs_dynamic_auth and afs_dynamic_kerbauth programs are +installed in the local /usr/vice/etc directory. +
```
   
+   # ls /usr/vice/etc   
+
```
+
If the files do not exist, mount the AFS CD-ROM for AIX (if it is not +already), change directory as indicated, and copy them. +
```
  
+   # cd /cdrom/rs_aix42/root.client/usr/vice/etc
+   
+   # cp  -p  afs_dynamic*  /usr/vice/etc
+   
+
```
+
Edit the local /etc/security/user file, making changes to the +indicated stanzas: +
- In the default stanza, set the registry attribute to +DCE (not to AFS), as follows: +
```
   
+   registry = DCE
+   
+
```
  +
- In the default stanza, set the SYSTEM attribute as +indicated. +
  If the machine is an AFS client only, set the following value: +
```
   
+   SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])"   
+
```
  +
  If the machine is both an AFS and a DCE client, set the following value (it +must appear on a single line in the file): +
```
   
+   SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL]  \
+       AND compat[SUCCESS])"
+   
+
```
  +
- In the root stanza, set the registry attribute as +follows. It enables the local superuser root to log into the +local file system only, based on the password listed in the local password +file. +
```
   
+   root:
+         registry = files
+   
+
```
  +
+
Edit the local /etc/security/login.cfg file, creating or +editing the indicated stanzas: +
- In the DCE stanza, set the program attribute as +follows. +
  If you use the AFS Authentication Server (kaserver +process): +
```
   
+   DCE:
+        program = /usr/vice/etc/afs_dynamic_auth   
+
```
  +
  If you use a Kerberos implementation of AFS authentication: +
```
   
+   DCE:
+        program = /usr/vice/etc/afs_dynamic_kerbauth
+   
+
```
  +
- In the AFS stanza, set the program attribute as +follows. +
  If you use the AFS Authentication Server (kaserver +process): +
```
   
+   AFS:
+        program = /usr/vice/etc/afs_dynamic_auth   
+
```
  +
  If you use a Kerberos implementation of AFS authentication: +
```
   
+   AFS:
+        program = /usr/vice/etc/afs_dynamic_kerbauth
+   
+
```
  +
+
Proceed to Loading and Creating Client Files. +

+ + + + + + + + + +

Getting Started on Digital UNIX Systems

In this section you build AFS into the Digital UNIX +kernel. Then incorporate AFS modifications into the machine's +Security Integration Architecture (SIA) matrix, if you wish to enable AFS +login. +

Building AFS into the Digital UNIX Kernel

On Digital UNIX systems, you must build AFS modifications into a new +static kernel; Digital UNIX does not support dynamic loading. If +the machine's hardware and software configuration exactly matches another +Digital UNIX machine on which AFS is already built into the kernel, you can +choose to copy the kernel from that machine to this one. In general, +however, it is better to build AFS modifications into the kernel on each +machine according to the following instructions. +

Create a copy called AFS of the basic kernel configuration file +included in the Digital UNIX distribution as +/usr/sys/conf/machine_name, where machine_name is +the machine's hostname in all uppercase letters. +
```
   
+   # cd /usr/sys/conf
+   
+   # cp machine_name AFS
+   
+
```
+

Add AFS to the list of options in the configuration file you created in +the previous step, so that the result looks like the following: +

          .                   .
+          .                   .
+       options               UFS
+       options               NFS
+       options               AFS
+          .                   .
+          .                   .
+   
+

Add an entry for AFS to two places in the file +/usr/sys/conf/files. +

Add a line for AFS to the list of OPTIONS, so that the result +looks like the following: +

             .                .      .
+             .                .      .
+      OPTIONS/nfs          optional nfs 
+      OPTIONS/afs          optional afs 
+      OPTIONS/nfs_server   optional nfs_server
+             .                .      .
+             .                .      .
+   
+

Add an entry for AFS to the list of MODULES, so that the result +looks like the following: +

             .                  .        .          .
+             .                  .        .          .
+      #
+      MODULE/nfs_server	    optional nfs_server Binary
+      nfs/nfs_server.c      module nfs_server optimize -g3
+      nfs/nfs3_server.c	    module nfs_server optimize -g3
+      #
+      MODULE/afs            optional afs Binary
+      afs/libafs.c          module afs
+      #
+   
+

Add an entry for AFS to two places in the file +/usr/sys/vfs/vfs_conf.c. +

Add AFS to the list of defined file systems, so that the result looks like +the following: +

        .       .              
+        .       .              
+     #include <afs.h>
+     #if defined(AFS) && AFS
+            extern struct vfsops afs_vfsops;
+     #endif  
+        .       .              
+        .       .              
+   
+

Put a declaration for AFS in the vfssw[] table's +MOUNT_ADDON slot, so that the result looks like the following: +

        .                          .              .
+        .                          .              .
+      &fdfs_vfsops,         "fdfs",   /* 12 = MOUNT_FDFS */
+   #if	defined(AFS)
+      &afs_vfsops,          "afs",
+   #else
+      (struct vfsops *)0,   "",       /* 13 = MOUNT_ADDON */
+   #endif
+   #if NFS && INFS_DYNAMIC   
+       &nfs3_vfsops,        "nfsv3",  /* 14 = MOUNT_NFS3 */		
+   
+

Mount the AFS CD-ROM for Digital UNIX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Digital UNIX documentation. Then change +directory as indicated. +
```
   
+   # cd /cdrom/alpha_dux40/root.client
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /sbin/init.d on Digital +UNIX machines). Note the removal of the .rc extension +as you copy the script. +
```
   
+   # cp usr/vice/etc/afs.rc  /sbin/init.d/afs
+   
+
```
+
Copy the AFS kernel module to the local /usr/sys/BINARY +directory. +
If the machine's kernel supports NFS server functionality: +
```
  
+   # cp bin/libafs.o /usr/sys/BINARY/afs.mod   
+
```
+
If the machine's kernel does not support NFS server +functionality: +
```
  
+   # cp bin/libafs.nonfs.o /usr/sys/BINARY/afs.mod
+   
+
```
+
Configure and build the kernel. Respond to any prompts by pressing +<Return>. The resulting kernel resides in the file +/sys/AFS/vmunix. +
```
   
+   # doconfig -c AFS
+   
+
```
+
Rename the existing kernel file and copy the new, AFS-modified file to the +standard location. +
```
   
+   # mv /vmunix /vmunix_noafs
+   
+   # cp /sys/AFS/vmunix /vmunix
+   
+
```
+

Reboot the machine to start using the new kernel, and login again as the +superuser root. +

   
+   # cd /
+   
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+

Enabling AFS Login on Digital UNIX Systems

Perform the following steps to enable AFS login. +

Mount the AFS CD-ROM for Digital UNIX on the local /cdrom +directory, if it is not already. Change directory as indicated. +
```
   
+   # cd /cdrom/alpha_dux40/lib/afs
+   
+
```
+
Copy the appropriate AFS authentication library file to the local +/usr/shlib directory. +
If you use the AFS Authentication Server (kaserver process) in +the cell: +
```
   
+   # cp  libafssiad.so  /usr/shlib   
+
```
+
If you use a Kerberos implementation of AFS authentication, rename the +library file as you copy it: +
```
   
+   # cp  libafssiad.krb.so  /usr/shlib/libafssiad.so
+   
+
```
+
Proceed to Loading and Creating Client Files. +

+ + + + + + + + + +

Getting Started on HP-UX Systems

In this section you build AFS into the HP-UX kernel. +Then incorporate AFS modifications into the machine's Pluggable +Authentication Module (PAM) system, if you wish to enable AFS login. +

Building AFS into the HP-UX Kernel

On HP-UX systems, you must build AFS modifications into a new static +kernel; HP-UX does not support dynamic loading. If the +machine's hardware and software configuration exactly matches another +HP-UX machine on which AFS is already built into the kernel, you can choose to +copy the kernel from that machine to this one. In general, however, it +is better to build AFS modifications into the kernel on each machine according +to the following instructions. +

Move the existing kernel-related files to a safe location. +

   
+   # cp /stand/vmunix /stand/vmunix.noafs
+   
+   # cp /stand/system /stand/system.noafs
+   
+

Mount the AFS CD-ROM for HP-UX on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your HP-UX documentation. Then change directory +as indicated. +
```
   
+   # cd /cdrom/hp_ux110/root.client
+   
+
```
+
Copy the AFS initialization file to the local directory for initialization +files (by convention, /sbin/init.d on HP-UX +machines). Note the removal of the .rc extension as +you copy the file. +
```
   
+   # cp usr/vice/etc/afs.rc  /sbin/init.d/afs
+   
+
```
+
Copy the file afs.driver to the local +/usr/conf/master.d directory, changing its name to +afs as you do. +
```
     
+   # cp  usr/vice/etc/afs.driver  /usr/conf/master.d/afs
+   
+
```
+
Copy the AFS kernel module to the local /usr/conf/lib +directory. +
If the machine's kernel supports NFS server functionality: +
```
   
+   # cp bin/libafs.a /usr/conf/lib   
+
```
+
If the machine's kernel does not support NFS server functionality, +change the file's name as you copy it: +
```
   
+   # cp bin/libafs.nonfs.a /usr/conf/lib/libafs.a
+   
+
```
+
Incorporate the AFS driver into the kernel, either using the +SAM program or a series of individual commands. +
- To use the SAM program: +
  1. Invoke the SAM program, specifying the hostname of the local +machine as local_hostname. The SAM graphical user +interface pops up. +
```
   
+   # sam -display local_hostname:0 
+   
+
```
    +
  2. Choose the Kernel Configuration icon, then the +Drivers icon. From the list of drivers, select +afs. +
  3. Open the pull-down Actions menu and choose the Add Driver +to Kernel option. +
  4. Open the Actions menu again and choose the Create a New +Kernel option. +
  5. Confirm your choices by choosing Yes and OK when +prompted by subsequent pop-up windows. The SAM program +builds the kernel and reboots the system. +
  6. Login again as the superuser root. +
```
   
+   login: root
+   Password: root_password
+   
+
```
    +
  +
- To use individual commands: +
  1. Edit the file /stand/system, adding an entry for afs +to the Subsystems section. +
  2. Change to the /stand/build directory and issue the +mk_kernel command to build the kernel. +
```
   
+   # cd /stand/build
+      
+   # mk_kernel
+   
+
```
    +
  3. Move the new kernel to the standard location (/stand/vmunix), +reboot the machine to start using it, and login again as the superuser +root. +
```
   
+   # mv /stand/build/vmunix_test /stand/vmunix
+      
+   # cd /
+      
+   # shutdown -r now		
+   
+   login: root
+   Password: root_password
+   
+
```
    +
  +
+

Enabling AFS Login on HP-UX Systems

The recommended AFS-related entries in the PAM configuration file make use +of one or more of the following three attributes. +

try_first_pass +: This is a standard PAM attribute that can be included on entries after the +first one for a service; it directs the module to use the password that +was provided to the first module. For the AFS module, it means that AFS +authentication succeeds if the password provided to the module listed first is +the user's correct AFS password. For further discussion of this +attribute and its alternatives, see the operating system's PAM +documentation. +
ignore_root +: This attribute, specific to the AFS PAM module, directs it to ignore not +only the local superuser root, but also any user with UID 0 +(zero). +
setenv_password_expires +: This attribute, specific to the AFS PAM module, sets the environment +variable PASSWORD_EXPIRES to the expiration date of the user's AFS +password, which is recorded in the Authentication Database. +

Perform the following steps to enable AFS login. +

Mount the AFS CD-ROM for HP-UX on the /cdrom directory, if it +is not already. Then change directory as indicated. +
```
  
+   # cd /usr/lib/security
+   
+
```
+
Copy the AFS authentication library file to the +/usr/lib/security directory. Then create a symbolic link to +it whose name does not mention the version. Omitting the version +eliminates the need to edit the PAM configuration file if you later update the +library file. +
If you use the AFS Authentication Server (kaserver process) in +the cell: +
```
   
+   # cp /cdrom/hp_ux110/lib/pam_afs.so.1  .
+  
+   # ln -s  pam_afs.so.1  pam_afs.so   
+
```
+
If you use a Kerberos implementation of AFS authentication: +
```
  
+   # cp /cdrom/hp_ux110/lib/pam_afs.krb.so.1   .
+  
+   # ln -s pam_afs.krb.so.1 pam_afs.so
+   
+
```
+
Edit the Authentication management section of the HP-UX PAM +configuration file, /etc/pam.conf by convention. The +entries in this section have the value auth in their second +field. +
First edit the standard entries, which refer to the HP-UX PAM module +(usually, the file /usr/lib/security/libpam_unix.1) in their +fourth field. For each service for which you want to use AFS +authentication, edit the third field of its entry to read +optional. The pam.conf file in the HP-UX +distribution usually includes standard entries for the login and +ftp services, for instance. +
If there are services for which you want to use AFS authentication, but for +which the pam.conf file does not already include a standard +entry, you must create that entry and place the value optional in +its third field. For instance, the HP-UX pam.conf +file does not usually include standard entries for the remsh or +telnet services. +
Then create an AFS-related entry for each service, placing it immediately +below the standard entry. The following example shows what the +Authentication Management section looks like after you have you +edited or created entries for the services mentioned previously. Note +that the example AFS entries appear on two lines only for legibility. +
```
   
+   login   auth  optional  /usr/lib/security/libpam_unix.1
+   login   auth  optional  /usr/lib/security/pam_afs.so      \
+         try_first_pass  ignore_root  setenv_password_expires
+   ftp     auth  optional  /usr/lib/security/libpam_unix.1
+   ftp     auth  optional  /usr/lib/security/pam_afs.so      \
+         try_first_pass  ignore_root
+   remsh   auth  optional  /usr/lib/security/libpam_unix.1
+   remsh   auth  optional  /usr/lib/security/pam_afs.so      \
+         try_first_pass  ignore_root		
+   telnet  auth  optional  /usr/lib/security/libpam_unix.1
+   telnet  auth  optional  /usr/lib/security/pam_afs.so      \
+         try_first_pass  ignore_root  setenv_password_expires
+   
+
```
+

  
+   dtlogin   auth  optional  /usr/lib/security/libpam_unix.1
+   dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
+         try_first_pass  ignore_root
+   dtaction  auth  optional  /usr/lib/security/libpam_unix.1
+   dtaction  auth  optional  /usr/lib/security/pam_afs.so     \
+         try_first_pass  ignore_root
+   
+

Proceed to Loading and Creating Client Files. +

+ + + +

Getting Started on IRIX Systems

In this section you incorporate AFS into the IRIX kernel, +choosing one of two methods: +

Dynamic loading using the ml program distributed by Silicon +Graphics, Incorporated (SGI). +
Building a new static kernel. +

Then see Enabling AFS Login on IRIX Systems to read about integrated AFS login on IRIX systems. +

In preparation for either dynamic loading or kernel building, perform the +following procedures: +

Mount the AFS CD-ROM for IRIX on the /cdrom directory. +For instructions on mounting CD-ROMs (either locally or remotely via NFS), see +your IRIX documentation. Then change directory as indicated. +
```
   
+   # cd  /cdrom/sgi_65/root.client
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/init.d on IRIX +machines). Note the removal of the .rc extension as +you copy the script. +
```
   
+   # cp -p   usr/vice/etc/afs.rc  /etc/init.d/afs
+   
+
```
+
Issue the uname -m command to determine the machine's CPU +board type. The IPxx value in the output must match +one of the supported CPU board types listed in the IBM AFS Release +Notes for the current version of AFS. +
```
   
+   # uname -m
+    
+
```
+
Proceed to either Loading AFS into the IRIX Kernel or Building AFS into the IRIX Kernel. +

+ + + + + + + +

Loading AFS into the IRIX Kernel

In a later section you verify that the script correctly initializes the +Cache Manager, then create the links that incorporate AFS into the IRIX +startup and shutdown sequence. +

Create the local /usr/vice/etc/sgiload directory to house the +AFS kernel library file. +
```
   
+   # mkdir /usr/vice/etc/sgiload
+   
+
```
+
Copy the appropriate AFS kernel library file to the +/usr/vice/etc/sgiload directory. The +IPxx portion of the library file name must match the value +previously returned by the uname -m command. Also choose the +file appropriate to whether the machine's kernel supports NFS server +functionality (NFS must be supported for the machine to act as an NFS/AFS +Translator). Single- and multiprocessor machines use the same library +file. +
(You can choose to copy all of the kernel library files into the +/usr/vice/etc/sgiload directory, but they require a significant amount +of space.) +
If the machine's kernel supports NFS server functionality: +
```
   
+   # cp -p  usr/vice/etc/sgiload/libafs.IPxx.o  /usr/vice/etc/sgiload   
+
```
+
If the machine's kernel does not support NFS server +functionality: +
```
   
+   # cp -p  usr/vice/etc/sgiload/libafs.IPxx.nonfs.o   \
+                   /usr/vice/etc/sgiload
+   
+
```
+
Issue the chkconfig command to activate the afsml +configuration variable. +
```
   
+   # /etc/chkconfig -f afsml on   
+
```
+
If the machine is to function as an NFS/AFS Translator and the kernel +supports NFS server functionality, activate the afsxnfs +variable. +
```
   
+   # /etc/chkconfig -f afsxnfs on
+   
+
```
+
Run the /etc/init.d/afs script to load AFS extensions +into the kernel. The script invokes the ml command, +automatically determining which kernel library file to use based on this +machine's CPU type and the activation state of the afsxnfs +variable. +
You can ignore any error messages about the inability to start the BOS +Server or the Cache Manager or AFS client. +
```
   
+   # /etc/init.d/afs start
+   
+
```
+
Proceed to Enabling AFS Login on IRIX Systems. +

+ +

Building AFS into the IRIX Kernel

If you prefer to build a kernel, and the machine's +hardware and software configuration exactly matches another IRIX machine on +which AFS is already built into the kernel, you can choose to copy the kernel +from that machine to this one. In general, however, it is better to +build AFS modifications into the kernel on each machine according to the +following instructions. +

Copy the kernel initialization file afs.sm to the local +/var/sysgen/system directory, and the kernel master file +afs to the local /var/sysgen/master.d +directory. +
```
   
+   # cp -p  bin/afs.sm  /var/sysgen/system
+   
+   # cp -p  bin/afs  /var/sysgen/master.d
+   
+
```
+
Copy the appropriate AFS kernel library file to the local file +/var/sysgen/boot/afs.a; the IPxx +portion of the library file name must match the value previously returned by +the uname -m command. Also choose the file appropriate to +whether the machine's kernel supports NFS server functionality (NFS must +be supported for the machine to act as an NFS/AFS Translator). Single- +and multiprocessor machines use the same library file. +
If the machine's kernel supports NFS server functionality: +
```
   
+   # cp -p   bin/libafs.IPxx.a   /var/sysgen/boot/afs.a   
+
```
+
If the machine's kernel does not support NFS server +functionality: +
```
   
+   # cp -p  bin/libafs.IPxx.nonfs.a  /var/sysgen/boot/afs.a
+   
+
```
+
Issue the chkconfig command to deactivate the afsml +configuration variable. +
```
   
+   # /etc/chkconfig -f afsml off   
+
```
+
If the machine is to function as an NFS/AFS Translator and the kernel +supports NFS server functionality, activate the afsxnfs +variable. +
```
    
+   # /etc/chkconfig -f afsxnfs on
+   
+
```
+
Copy the existing kernel file, /unix, to a safe +location. Compile the new kernel, which is created in the file +/unix.install. It overwrites the existing +/unix file when the machine reboots in the next step. +
```
   
+   # cp /unix /unix_noafs
+   
+   # autoconfig
+   
+
```
+

Reboot the machine to start using the new kernel, and login again as the +superuser root. +

   
+   # cd /
+         
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+

Proceed to Enabling AFS Login on IRIX Systems. +

+ + + +

Enabling AFS Login on IRIX Systems

The standard IRIX command-line login program and +the graphical xdm login program both automatically grant an AFS +token when AFS is incorporated into the machine's kernel. However, +some IRIX distributions use another login utility by default, and it does not +necessarily incorporate the required AFS modifications. If that is the +case, you must disable the default utility if you want AFS users to obtain AFS +tokens at login. For further discussion, see the IBM AFS Release +Notes. +

  
+   # ls /usr/vice/etc   
+

If the files do not exist, mount the AFS CD-ROM for IRIX (if it is not +already), change directory as indicated, and copy them. +

  
+   # cd /cdrom/sgi_65/root.client/usr/vice/etc
+   
+   # cp  -p  *authlib*  /usr/vice/etc   
+

After taking any necessary action, proceed to Loading and Creating Client Files. + + + + + + + + + +

Getting Started on Linux Systems

In this section you load AFS into the Linux kernel. +Then incorporate AFS modifications into the machine's Pluggable +Authentication Module (PAM) system, if you wish to enable AFS login. +

Loading AFS into the Linux Kernel

The insmod program is the dynamic kernel loader for +Linux. Linux does not support incorporation of AFS modifications during +a kernel build. +

In a later section you also verify that the script correctly initializes +the Cache Manager, then activate a configuration variable, which results in +the script being incorporated into the Linux startup and shutdown +sequence. +

Mount the AFS CD-ROM for Linux on the local /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Linux documentation. Then change directory +as indicated. +
```
   
+   # cd  /cdrom/i386_linux22/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS kernel library files to the local +/usr/vice/etc/modload directory. The filenames for the +libraries have the format +libafs-version.o, where version +indicates the kernel build level. The string .mp in +the version indicates that the file is appropriate for machines +running a multiprocessor kernel. +
```
   
+   # cp -rp  modload  /usr/vice/etc
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/rc.d/init.d +on Linux machines). Note the removal of the .rc +extension as you copy the script. +
```
   
+   # cp -p   afs.rc  /etc/rc.d/init.d/afs 
+    
+
```
+
Run the AFS initialization script to load AFS extensions into the +kernel. You can ignore any error messages about the inability to start +the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/rc.d/init.d/afs  start
+   
+
```
+

Enabling AFS Login on Linux Systems

The recommended AFS-related entries in the PAM configuration file make use +of one or more of the following three attributes. +

try_first_pass +: This is a standard PAM attribute that can be included on entries after the +first one for a service; it directs the module to use the password that +was provided to the first module. For the AFS module, it means that AFS +authentication succeeds if the password provided to the module listed first is +the user's correct AFS password. For further discussion of this +attribute and its alternatives, see the operating system's PAM +documentation. +
ignore_root +: This attribute, specific to the AFS PAM module, directs it to ignore not +only the local superuser root, but also any user with UID 0 +(zero). +
setenv_password_expires +: This attribute, specific to the AFS PAM module, sets the environment +variable PASSWORD_EXPIRES to the expiration date of the user's AFS +password, which is recorded in the Authentication Database. +

Perform the following steps to enable AFS login. +

Mount the AFS CD-ROM for Linux on the /cdrom directory, if it +is not already. Then change to the directory for PAM modules, which +depends on which Linux distribution you are using. +
If you are using a Linux distribution from Red Hat Software: +
```
   
+   # cd /lib/security   
+
```
+
If you are using another Linux distribution: +
```
   
+   # cd /usr/lib/security
+   
+
```
+
Copy the appropriate AFS authentication library file to the directory to +which you changed in the previous step. Create a symbolic link whose +name does not mention the version. Omitting the version eliminates the +need to edit the PAM configuration file if you later update the library +file. +
If you use the AFS Authentication Server (kaserver +process): +
```
   
+   # cp /cdrom/i386_linux22/lib/pam_afs.so.1  .
+   
+   # ln -s pam_afs.so.1 pam_afs.so   
+
```
+
If you use a Kerberos implementation of AFS authentication: +
```
   
+   # cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1   .
+   
+   # ln -s pam_afs.krb.so.1 pam_afs.so
+   
+
```
+
For each service with which you want to use AFS authentication, insert an +entry for the AFS PAM module into the auth section of the +service's PAM configuration file. (Linux uses a separate +configuration file for each service, unlike some other operating systems which +list all services in a single file.) Mark the entry as +sufficient in the second field. +
Place the AFS entry below any entries that impose conditions under which +you want the service to fail for a user who does not meet the entry's +requirements. Mark these entries required. Place the +AFS entry above any entries that need to execute only if AFS authentication +fails. +
Insert the following AFS entry if using the Red Hat distribution: +
```
   
+   auth  sufficient  /lib/security/pam_afs.so   try_first_pass  ignore_root   
+
```
+
Insert the following AFS entry if using another distribution: +
```
   
+   auth  sufficient  /usr/lib/security/pam_afs.so  try_first_pass  ignore_root   
+
```
+
The following example illustrates the recommended configuration of the +configuration file for the login service +(/etc/pam.d/login) on a machine using the Red Hat +distribution. +
```
   
+   #%PAM-1.0
+   auth      required   /lib/security/pam_securetty.so
+   auth      required   /lib/security/pam_nologin.so
+   auth      sufficient /lib/security/pam_afs.so try_first_pass ignore_root
+   auth      required   /lib/security/pam_pwdb.so shadow nullok
+   account   required   /lib/security/pam_pwdb.so
+   password  required   /lib/security/pam_cracklib.so
+   password  required   /lib/security/pam_pwdb.so shadow nullok use_authtok
+   session   required   /lib/security/pam_pwdb.so
+   
+
```
+
Proceed to Loading and Creating Client Files. +

+ + + + + + + + + + + + +

Getting Started on Solaris Systems

In this section you load AFS into the Solaris kernel. +Then incorporate AFS modifications into the machine's Pluggable +Authentication Module (PAM) system, if you wish to enable AFS login. +

Loading AFS into the Solaris Kernel

The modload program is the dynamic kernel loader provided by +Sun Microsystems for Solaris systems. Solaris does not support +incorporation of AFS modifications during a kernel build. +

In a later section you verify that the script correctly initializes the +Cache Manager, then create the links that incorporate AFS into the Solaris +startup and shutdown sequence. +

Mount the AFS CD-ROM for Solaris on the /cdrom +directory. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), see your Solaris documentation. Then change +directory as indicated. +
```
   
+   # cd  /cdrom/sun4x_56/root.client/usr/vice/etc
+   
+
```
+
Copy the AFS initialization script to the local directory for +initialization files (by convention, /etc/init.d on Solaris +machines). Note the removal of the .rc extension as +you copy the script. +
```
   
+   # cp -p  afs.rc  /etc/init.d/afs
+   
+
```
+
Copy the appropriate AFS kernel library file to the local file +/kernel/fs/afs. +
If the machine is running Solaris 2.6 or the 32-bit version of +Solaris 7, its kernel supports NFS server functionality, and the +nfsd process is running: +
```
   
+   # cp -p modload/libafs.o /kernel/fs/afs   
+
```
+
If the machine is running Solaris 2.6 or the 32-bit version of +Solaris 7, and its kernel does not support NFS server functionality or the +nfsd process is not running: +
```
   
+   # cp -p modload/libafs.nonfs.o /kernel/fs/afs   
+
```
+
If the machine is running the 64-bit version of Solaris 7, its kernel +supports NFS server functionality, and the nfsd process is +running: +
```
   
+   # cp -p modload/libafs64.o /kernel/fs/sparcv9/afs   
+
```
+
If the machine is running the 64-bit version of Solaris 7, and its +kernel does not support NFS server functionality or the nfsd +process is not running: +
```
   
+   # cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs
+   
+
```
+
Run the AFS initialization script to load AFS modifications into the +kernel. You can ignore any error messages about the inability to start +the BOS Server or the Cache Manager or AFS client. +
```
   
+   # /etc/init.d/afs start   
+
```
+
When an entry called afs does not already exist in the local +/etc/name_to_sysnum file, the script automatically creates it and +reboots the machine to start using the new version of the file. If this +happens, log in again as the superuser root after the reboot and +run the initialization script again. This time the required entry +exists in the /etc/name_to_sysnum file, and the modload +program runs. +
```
   
+   login: root
+   Password: root_password
+   
+   # /etc/init.d/afs start
+   
+
```
+

Enabling AFS Login on Solaris Systems

The recommended AFS-related entries in the PAM configuration file make use +of one or more of the following three attributes. +

try_first_pass +: This is a standard PAM attribute that can be included on entries after the +first one for a service; it directs the module to use the password that +was provided to the first module. For the AFS module, it means that AFS +authentication succeeds if the password provided to the module listed first is +the user's correct AFS password. For further discussion of this +attribute and its alternatives, see the operating system's PAM +documentation. +
ignore_root +: This attribute, specific to the AFS PAM module, directs it to ignore not +only the local superuser root, but also any user with UID 0 +(zero). +
setenv_password_expires +: This attribute, specific to the AFS PAM module, sets the environment +variable PASSWORD_EXPIRES to the expiration date of the user's AFS +password, which is recorded in the Authentication Database. +

Perform the following steps to enable AFS login. +

Mount the AFS CD-ROM for Solaris on the /cdrom directory, if it +is not already. Then change directory as indicated. +
```
  
+   # cd /usr/lib/security
+   
+
```
+
Copy the AFS authentication library file to the +/usr/lib/security directory. Then create a symbolic link to +it whose name does not mention the version. Omitting the version +eliminates the need to edit the PAM configuration file if you later update the +library file. +
If you use the AFS Authentication Server (kaserver +process): +
```
  
+   # cp /cdrom/sun4x_56/lib/pam_afs.so.1 .
+  
+   # ln -s pam_afs.so.1 pam_afs.so   
+
```
+
If you use a Kerberos implementation of AFS authentication: +
```
     
+   # cp /cdrom/sun4x_56/lib/pam_afs.krb.so.1 .
+  
+   # ln -s pam_afs.krb.so.1 pam_afs.so
+   
+
```
+
Edit the Authentication management section of the Solaris PAM +configuration file, /etc/pam.conf by convention. The +entries in this section have the value auth in their second +field. +
First edit the standard entries, which refer to the Solaris PAM module +(usually, the file /usr/lib/security/pam_unix.so.1) +in their fourth field. For each service for which you want to use AFS +authentication, edit the third field of its entry to read +optional. The pam.conf file in the Solaris +distribution usually includes standard entries for the login, +rlogin, and rsh services, for instance. +
If there are services for which you want to use AFS authentication, but for +which the pam.conf file does not already include a standard +entry, you must create that entry and place the value optional in +its third field. For instance, the Solaris pam.conf +file does not usually include standard entries for the ftp or +telnet services. +
Then create an AFS-related entry for each service, placing it immediately +below the standard entry. The following example shows what the +Authentication Management section looks like after you have you +edited or created entries for the services mentioned previously. Note +that the example AFS entries appear on two lines only for legibility. +
```
  
+   login   auth  optional  /usr/lib/security/pam_unix.so.1
+   login   auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root  setenv_password_expires
+   rlogin  auth  optional  /usr/lib/security/pam_unix.so.1
+   rlogin  auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root  setenv_password_expires
+   rsh     auth  optional  /usr/lib/security/pam_unix.so.1
+   rsh     auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root		
+   ftp     auth  optional  /usr/lib/security/pam_unix.so.1
+   ftp     auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root
+   telnet  auth  optional  /usr/lib/security/pam_unix.so.1
+   telnet  auth  optional  /usr/lib/security/pam_afs.so       \
+         try_first_pass  ignore_root  setenv_password_expires
+   
+
```
+

   
+   dtlogin   auth  optional  /usr/lib/security/pam_unix.so.1
+   dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
+         try_first_pass  ignore_root
+   dtsession  auth  optional /usr/lib/security/pam_unix.so.1
+   dtsession  auth  optional /usr/lib/security/pam_afs.so     \
+         try_first_pass  ignore_root
+   
+

Some Solaris distributions include a script that locates and removes +unneeded files from various file systems. Its conventional location is +/usr/lib/fs/nfs/nfsfind. The script generally uses an +argument to the find command to define which file systems to +search. In this step you modify the command to exclude the +/afs directory. Otherwise, the command traverses the AFS +filespace of every cell that is accessible from the machine, which can take +many hours. The following alterations are possibilities, but you must +verify that they are appropriate for your cell. +
The first possible alteration is to add the -local flag to the +existing command, so that it looks like the following: +
```
  
+   find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;   
+
```
+
Another alternative is to exclude any directories whose names begin with +the lowercase letter a or a non-alphabetic character. +
```
  
+   find /[A-Zb-z]*  remainder of existing command   
+
```
+
Do not use the following command, which still searches under the +/afs directory, looking for a subdirectory of type +4.2. +
```
  
+   find / -fstype 4.2     /* do not use */
+   
+
```
+
Proceed to Loading and Creating Client Files. +

+ + + + + + + + + + + + +

Loading and Creating Client Files

Now copy files from the AFS CD-ROM to the +/usr/vice/etc directory. On some platforms that use a +dynamic loader program to incorporate AFS modifications into the kernel, you +have already copied over some the files. Copying them again does no +harm. +

The cell in which users authenticate when they log onto the machine, +assuming it is using an AFS-modified login utility +
The cell in which users authenticate by default when they issue the +klog command +
The cell membership of the AFS server processes that the AFS command +interpreters on this machine contact by default +

Similarly, the /usr/vice/etc/CellServDB file on a client +machine's local disk lists the database server machines in each cell that +the local Cache Manager can contact. If there is no entry in the file +for a cell, or the list of database server machines is wrong, then users +working on this machine cannot access the cell. The chapter in the +IBM AFS Administration Guide about administering client machines +explains how to maintain the file after creating it. A version of the +client CellServDB file was created during the installation of your +cell's first machine (in Creating the Client CellServDB File). It is probably also appropriate for use on this +machine. +

Remember that the Cache Manager consults the +/usr/vice/etc/CellServDB file only at reboot, when it copies the +information into the kernel. For the Cache Manager to perform properly, +the CellServDB file must be accurate at all times. Refer to +the chapter in the IBM AFS Administration Guide about administering +client machines for instructions on updating this file, with or without +rebooting. +

On the local /cdrom directory, mount the AFS CD-ROM for this +machine's system type, if it is not already. For instructions on +mounting CD-ROMs (either locally or remotely via NFS), consult the operating +system documentation. +
Copy files to the local /usr/vice/etc directory. +
This step places a copy of the AFS initialization script (and related +files, if applicable) into the /usr/vice/etc directory. In +the preceding instructions for incorporating AFS into the kernel, you copied +the script directly to the operating system's conventional location for +initialization files. When you incorporate AFS into the machine's +startup sequence in a later step, you can choose to link the two files. +
On some system types that use a dynamic kernel loader program, you +previously copied AFS library files into a subdirectory of the +/usr/vice/etc directory. On other system types, you copied +the appropriate AFS library file directly to the directory where the operating +system accesses it. The following commands do not copy or recopy the +AFS library files into the /usr/vice/etc directory, because on some +system types the library files consume a large amount of space. If you +want to copy them, add the -r flag to the first cp +command and skip the second cp command. +
```
   
+   # cd /cdrom/sysname/root.client/usr/vice/etc
+   
+   # cp -p  *  /usr/vice/etc
+  
+   # cp -rp  C  /usr/vice/etc
+   
+
```
+

Create the /usr/vice/etc/ThisCell file. +

   
+   # echo "cellname" > /usr/vice/etc/ThisCell
+    
+

Create the /usr/vice/etc/CellServDB file. Use a network +file transfer program such as ftp or NFS to copy it from one of the +following sources, which are listed in decreasing order of preference: +
- Your cell's central CellServDB source file (the +conventional location is +/afs/cellname/common/etc/CellServDB) +
- The global CellServDB file maintained by the AFS Product +Support group +
- An existing client machine in your cell +
- The CellServDB.sample file included in the +sysname/root.client/usr/vice/etc directory of each +AFS CD-ROM; add an entry for the local cell by following the instructions +in Creating the Client CellServDB File +
+

+ + + + + + + + + + + + + + + + +

Configuring the Cache

The first field names the local directory on which to mount the AFS +filespace. The conventional location is the /afs +directory. +
The second field defines the local disk directory to use for the disk +cache. The conventional location is the /usr/vice/cache +directory, but you can specify an alternate directory if another partition has +more space available. There must always be a value in this field, but +the Cache Manager ignores it if the machine uses a memory cache. +
The third field specifies the number of kilobyte (1024 byte) blocks to +allocate for the cache. +

The values you define must meet the following requirements. +

On a machine using a disk cache, the Cache Manager expects always to be +able to use the amount of space specified in the third field. Failure +to meet this requirement can cause serious problems, some of which can be +repaired only by rebooting. You must prevent non-AFS processes from +filling up the cache partition. The simplest way is to devote a +partition to the cache exclusively. +
The amount of space available in memory or on the partition housing the +disk cache directory imposes an absolute limit on cache size. +
The maximum supported cache size can vary in each AFS release; see +the IBM AFS Release Notes for the current version. +
For a disk cache, you cannot specify a value in the third field that +exceeds 95% of the space available on the partition mounted at the directory +named in the second field. If you violate this restriction, the +afsd program exits without starting the Cache Manager and prints an +appropriate message on the standard output stream. A value of 90% is +more appropriate on most machines. Some operating systems (such as AIX) +do not automatically reserve some space to prevent the partition from filling +completely; for them, a smaller value (say, 80% to 85% of the space +available) is more appropriate. +
For a memory cache, you must leave enough memory for other processes and +applications to run. If you try to allocate more memory than is +actually 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
+
```
+
The number value is how many kilobytes were allocated just before +the failure, and so indicates the approximate amount of memory +available. +

Configuring a Disk Cache

Note:

Not all file system types that an operating system supports +are necessarily supported for use as the cache partition. For possible +restrictions, see the IBM AFS Release Notes. +

To configure the disk cache, perform the following procedures: +

Create the local directory to use for caching. The following +instruction shows the conventional location, +/usr/vice/cache. If you are devoting a partition exclusively +to caching, as recommended, you must also configure it, make a file system on +it, and mount it at the directory created in this step. +
```
   
+   # mkdir /usr/vice/cache
+   
+
```
+
Create the cacheinfo file to define the configuration +parameters discussed previously. The following instruction shows the +standard mount location, /afs, and the standard cache location, +/usr/vice/cache. +
```
   
+   # echo "/afs:/usr/vice/cache:#blocks" > /usr/vice/etc/cacheinfo
+
```
+
The following example defines the disk cache size as 50,000 KB: +
```
   
+   # echo "/afs:/usr/vice/cache:50000" > /usr/vice/etc/cacheinfo
+
```
+

Configuring a Memory Cache

   
+   # echo "/afs:/usr/vice/cache:#blocks" > /usr/vice/etc/cacheinfo
+

The following example allocates 25,000 KB of memory for the cache. +

   
+   # echo "/afs:/usr/vice/cache:25000" > /usr/vice/etc/cacheinfo
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Configuring the Cache Manager

By convention, the Cache Manager mounts the AFS filespace on +the local /afs directory. In this section you create that +directory. +

You can create an afsd options file that sets values +for arguments to the afsd command. If the file exists, its +contents are automatically substituted for the OPTIONS variable in +the AFS initialization script. The AFS distribution for some system +types includes an options file; on other system types, you must create +it. +
You use two variables in the AFS initialization script to specify the path +to the options file: CONFIG and AFSDOPT. On +system types that define a conventional directory for configuration files, the +CONFIG variable indicates it by default; otherwise, the +variable indicates an appropriate location. +
List the desired afsd options on a single line in the options +file, separating each option with one or more spaces. The following +example sets the -stat argument to 2500, the -daemons +argument to 4, and the -volumes argument to 100. +
```
   
+   -stat 2500 -daemons 4 -volumes 100   
+   
+
```
+
On a machine that uses a disk cache, you can set the OPTIONS +variable in the AFS initialization script to one of $SMALL, +$MEDIUM, or $LARGE. The AFS initialization script +uses one of these settings if the afsd options file named by the +AFSDOPT variable does not exist. In the script as +distributed, the OPTIONS variable is set to the value +$MEDIUM. +
Note: Do not set the OPTIONS variable to $SMALL, +$MEDIUM, or $LARGE on a machine that uses a memory +cache. The arguments it sets are appropriate only on a machine that +uses a disk cache. +
+
The script (or on some system types the afsd options file named +by the AFSDOPT variable) defines a value for each of +SMALL, MEDIUM, and LARGE that sets +afsd command arguments appropriately for client machines of +different sizes: +
- SMALL is suitable for a small machine that serves one or two +users and has approximately 8 MB of RAM and a 20-MB cache +
- MEDIUM is suitable for a medium-sized machine that serves two +to six users and has 16 MB of RAM and a 40-MB cache +
- LARGE is suitable for a large machine that serves five to ten +users and has 32 MB of RAM and a 100-MB cache +
+
You can choose not to create an afsd options file and to set +the OPTIONS variable in the initialization script to a null value +rather than to the default $MEDIUM value. You can then +either set arguments directly on the afsd command line in the +script, or set no arguments (and so accept default values for all Cache +Manager parameters). +

Create the local directory on which to mount the AFS filespace, by +convention /afs. If the directory already exists, verify +that it is empty. +
```
   
+   # mkdir /afs
+   
+
```
+
On AIX systems, add the following line to the /etc/vfs +file. It enables AIX to unmount AFS correctly during shutdown. +
```
   
+   afs     4     none     none
+   
+
```
+
On Linux systems, copy the afsd options file from the +/usr/vice/etc directory to the /etc/sysconfig directory, +removing the .conf extension as you do so. +
```
   
+   # cp /usr/vice/etc/afs.conf /etc/sysconfig/afs
+   
+
```
+
Edit the machine's AFS initialization script or afsd +options file to set appropriate values for afsd command +parameters. The appropriate file for each system type is as +follows: +
- On AIX systems, /etc/rc.afs +
- On Digital UNIX systems, /sbin/init.d/afs +
- On HP-UX systems, /sbin/init.d/afs +
- On IRIX systems, /etc/init.d/afs +
- On Linux systems, /etc/sysconfig/afs (the afsd +options file) +
- On Solaris systems, /etc/init.d/afs +
+
Use one of the methods described in the introduction to this section to add +the following flags to the afsd command line. Also set any +performance-related arguments you wish. +
- Add the -memcache flag if the machine is to use a memory +cache. +
- Add the -verbose flag to display a trace of the Cache +Manager's initialization on the standard output stream. +
+

+ + + + + +

Starting the Cache Manager and Installing the AFS Initialization Script

In this section you run the AFS initialization script to +start the Cache Manager. If the script works correctly, perform the +steps that incorporate it into the machine's startup and shutdown +sequence. If there are problems during the initialization, attempt to +resolve them. The AFS Product Support group can provide assistance if +necessary. +

On machines that use a disk cache, it can take a while for the +afsd program to run the first time on a machine, because it must +create all of the Vn files in the cache directory. +Subsequent Cache Manager initializations do not take nearly as long, because +the Vn files already exist. +

On system types that use a dynamic loader program, you must reboot the +machine before running the initialization script, so that it can freshly load +AFS modifications into the kernel. +

Proceed to the instructions for your system type: +

Running the Script on AIX Systems +
Running the Script on Digital UNIX Systems +
Running the Script on HP-UX Systems +
Running the Script on IRIX Systems +
Running the Script on Linux Systems +
Running the Script on Solaris Systems +

+ + + + +

Running the Script on AIX Systems

Reboot the machine and log in again as the local superuser +root. +

   
+   # cd /
+   
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+

Run the AFS initialization script. +
```
   
+   # /etc/rc.afs
+   
+
```
+
Edit the AIX initialization file, /etc/inittab, adding the +following line to invoke the AFS initialization script. Place it just +after the line that starts NFS daemons. +
```
   
+   rcafs:2:wait:/etc/rc.afs > /dev/console 2>&1 # Start AFS services
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc directories. +If you want to avoid potential confusion by guaranteeing that they are always +the same, create a link between them. You can always retrieve the +original script from the AFS CD-ROM if necessary. +
```
   
+   # cd  /usr/vice/etc
+   
+   # rm  rc.afs
+  
+   # ln -s  /etc/rc.afs
+   
+
```
+
If a volume for housing AFS binaries for this machine's system type +does not already exist, proceed to Setting Up Volumes and Loading Binaries into AFS. Otherwise, the installation is complete. +

+ + + + +

Running the Script on Digital UNIX Systems

Run the AFS initialization script. +

   
+   # /sbin/init.d/afs  start
+   
+

Change to the /sbin/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the Digital UNIX startup and shutdown +sequence. +
```
   
+   # cd  /sbin/init.d
+   
+   # ln -s  ../init.d/afs  /sbin/rc3.d/S67afs
+   
+   # ln -s  ../init.d/afs  /sbin/rc0.d/K66afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /sbin/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /sbin/init.d/afs  afs.rc
+   
+
```
+
If a volume for housing AFS binaries for this machine's system type +does not already exist, proceed to Setting Up Volumes and Loading Binaries into AFS. Otherwise, the installation is complete. +

+ + + +

Running the Script on HP-UX Systems

Run the AFS initialization script. +

   
+   # /sbin/init.d/afs  start
+   
+

Change to the /sbin/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the HP-UX startup and shutdown sequence. +
```
   
+   # cd /sbin/init.d
+   
+   # ln -s ../init.d/afs /sbin/rc2.d/S460afs
+  
+   # ln -s ../init.d/afs /sbin/rc2.d/K800afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /sbin/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /sbin/init.d/afs  afs.rc
+   
+
```
+
If a volume for housing AFS binaries for this machine's system type +does not already exist, proceed to Setting Up Volumes and Loading Binaries into AFS. Otherwise, the installation is complete. +

+ + + + + + + +

Running the Script on IRIX Systems

If you have configured the machine to use the ml dynamic loader +program, reboot the machine and log in again as the local superuser +root. +
```
   
+   # cd /
+         
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+
```
+
Issue the chkconfig command to activate the +afsclient configuration variable. +
```
  
+   # /etc/chkconfig -f afsclient on 
+   
+
```
+
Run the AFS initialization script. +
```
   
+   # /etc/init.d/afs  start
+   
+
```
+
Change to the /etc/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the IRIX startup and shutdown sequence. +
```
   
+   # cd /etc/init.d
+   
+   # ln -s ../init.d/afs /etc/rc2.d/S35afs
+  
+   # ln -s ../init.d/afs /etc/rc0.d/K35afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /etc/init.d/afs  afs.rc
+   
+
```
+
If a volume for housing AFS binaries for this machine's system type +does not already exist, proceed to Setting Up Volumes and Loading Binaries into AFS. Otherwise, the installation is complete. +

+ + + + +

Running the Script on Linux Systems

Reboot the machine and log in again as the local superuser +root. +

  
+   # cd /
+         
+   # shutdown -r now
+   
+   login: root
+   Password: root_password
+   
+

Run the AFS initialization script. +

   
+   # /etc/rc.d/init.d/afs  start
+   
+

Issue the chkconfig command to activate the afs +configuration variable. Based on the instruction in the AFS +initialization file that begins with the string #chkconfig, the +command automatically creates the symbolic links that incorporate the script +into the Linux startup and shutdown sequence. +
```
   
+   # /sbin/chkconfig  --add afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and +/etc/rc.d/init.d directories, and copies of the +afsd options file in both the /usr/vice/etc and +/etc/sysconfig directories. If you want to avoid potential +confusion by guaranteeing that the two copies of each file are always the +same, create a link between them. You can always retrieve the original +script or options file from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc afs.conf
+    
+   # ln -s  /etc/rc.d/init.d/afs  afs.rc
+   
+   # ln -s  /etc/sysconfig/afs  afs.conf
+   
+
```
+
If a volume for housing AFS binaries for this machine's system type +does not already exist, proceed to Setting Up Volumes and Loading Binaries into AFS. Otherwise, the installation is complete. +

+ + + +

Running the Script on Solaris Systems

Reboot the machine and log in again as the local superuser +root. +

   
+   # cd /
+      
+   # shutdown -i6 -g0 -y
+   
+   login: root
+   Password: root_password
+   
+

Run the AFS initialization script. +
```
   
+   # /etc/init.d/afs  start
+   
+
```
+
Change to the /etc/init.d directory and issue the +ln -s command to create symbolic links that incorporate the AFS +initialization script into the Solaris startup and shutdown sequence. +
```
   
+   # cd /etc/init.d
+  
+   # ln -s ../init.d/afs /etc/rc3.d/S99afs
+  
+   # ln -s ../init.d/afs /etc/rc0.d/K66afs
+   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc/init.d +directories. If you want to avoid potential confusion by guaranteeing +that they are always the same, create a link between them. You can +always retrieve the original script from the AFS CD-ROM if necessary. +
```
   
+   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /etc/init.d/afs  afs.rc
+   
+
```
+
If a volume for housing AFS binaries for this machine's system type +does not already exist, proceed to Setting Up Volumes and Loading Binaries into AFS. Otherwise, the installation is complete. +

+ + + + + + +

Setting Up Volumes and Loading Binaries into AFS

In this section, you link /usr/afsws on the local +disk to the directory in AFS that houses AFS binaries for this system +type. The conventional name for the AFS directory is +/afs/cellname/sysname/usr/afsws. +

If this machine is an existing system type, the AFS directory presumably +already exists. You can simply create a link from the local +/usr/afsws directory to it. Follow the instructions in Linking /usr/afsws on an Existing System Type. +

If this machine is a new system type (there are no AFS machines of this +type in your cell), you must first create and mount volumes to store its AFS +binaries, and then create the link from /usr/afsws to the new +directory. See Creating Binary Volumes for a New System Type. +

You can also store UNIX system binaries (the files normally stored in local +disk directories such as /bin, /etc, and +/lib) in volumes mounted under +/afs/cellname/sysname. See Storing System Binaries in AFS . +

Linking /usr/afsws on an Existing System Type

If this client machine is an existing system type, there is +already a volume mounted in the AFS filespace that houses AFS client binaries +for it. +

Create /usr/afsws on the local disk as a symbolic link to the +directory /afs/cellname/@sys/usr/afsws. +You can specify the actual system name instead of @sys if you wish, +but the advantage of using @sys is that it remains valid if you +upgrade this machine to a different system type. +
```
   
+   # ln -s /afs/cellname/@sys/usr/afsws  /usr/afsws
+   
+
```
+
(Optional) If you believe it is helpful to your users to access +the AFS documents in a certain format via a local disk directory, create +/usr/afsdoc on the local disk as a symbolic link to the +documentation directory in AFS +(/afs/cellname/afsdoc/format_name). +
+
```
   
+   # ln -s /afs/cellname/afsdoc/format_name /usr/afsdoc
+
```
+
An alternative is to create a link in each user's home directory to +the /afs/cellname/afsdoc/format_name +directory. +

Creating Binary Volumes for a New System Type

If this client machine is a new system type, you must create +and mount volumes for its binaries before you can link the local +/usr/afsws directory to an AFS directory. +

To create and mount the volumes, you use the klog command to +authenticate as an administrator and then issue commands from the +vos and fs command suites. However, the command +binaries are not yet available on this machine (by convention, they are +accessible via the /usr/afsws link that you are about to +create). You have two choices: +

Perform all steps except the last one (Step 10) on an existing AFS machine. On a file server +machine, the klog, fs and vos binaries reside +in the /usr/afs/bin directory. On client machines, the +klog and fs binaries reside in the +/usr/afsws/bin directory and the vos binary in the +/usr/afsws/etc directory. Depending on how your PATH +environment variable is set, you possibly need to precede the command names +with a pathname. +
If you work on another AFS machine, be sure to substitute the new system +type name for the sysname argument in the following commands, not the +system type of the machine on which you are issuing the commands. +
Copy the necessary command binaries to a temporary location on the local +disk, which enables you to perform the steps on the local machine. The +following procedure installs them in the /tmp directory and removes +them at the end. Depending on how your PATH environment variable is +set, you possibly need to precede the command names with a pathname. +

Perform the following steps to create a volume for housing AFS +binaries. +

Working either on the local machine or another AFS machine, mount the AFS +CD-ROM for the new system type on the /cdrom directory, if it is +not already. For instructions on mounting CD-ROMs (either locally or +remotely via NFS), consult the operating system documentation. +
If working on the local machine, copy the necessary binaries to a +temporary location on the local disk. Substitute a different directory +name for /tmp if you wish. +
```
   
+   # cd  /cdrom/new_sysname/root.server/usr/afs/bin
+   
+   # cp -p  klog  /tmp
+ 
+   # cp -p  fs  /tmp
+ 
+   # cp -p  vos  /tmp
+     
+
```
+

Authenticate as the user admin. +

   
+   # klog admin
+   Password: admin_password
+    
+

Issue the vos create command to create volumes for +storing the AFS client binaries for this system type. The following +example instruction creates volumes called sysname, +sysname.usr, and +sysname.usr.afsws. Refer to the +IBM AFS Release Notes to learn the proper value of sysname +for this system type. +
```
    
+   # vos create <machine name> <partition name> sysname
+     
+   # vos create <machine name> <partition name> sysname.usr
+     
+   # vos create <machine name> <partition name> sysname.usr.afsws
+    
+
```
+
Issue the fs mkmount command to mount the newly created +volumes. Because the root.cell volume is replicated, +you must precede the cellname part of the pathname with a period to +specify the read/write mount point, as shown. Then issue the vos +release command to release a new replica of the +root.cell volume, and the fs checkvolumes command +to force the local Cache Manager to access them. +
```
   
+   # fs mkmount -dir /afs/.cellname/sysname -vol sysname
+   
+   # fs mkmount -dir /afs/.cellname/sysname/usr  -vol sysname.usr
+   
+   # fs mkmount -dir /afs/.cellname/sysname/usr/afsws -vol sysname.usr.afsws
+   
+   # vos release root.cell
+   
+   # fs checkvolumes
+   
+
```
+
Issue the fs setacl command to grant the l +(lookup) and r (read) permissions to the +system:anyuser group on each new directory's ACL. +
```
   
+   # cd /afs/.cellname/sysname
+   
+   # fs setacl  -dir  .  usr  usr/afsws  -acl  system:anyuser rl 
+   
+
```
+
Issue the fs setquota command to set an unlimited quota on the +volume mounted at the +/afs/cellname/sysname/usr/afsws +directory. This enables you to copy all of the appropriate files from +the CD-ROM into the volume without exceeding the volume's quota. +
If you wish, you can set the volume's quota to a finite value after +you complete the copying operation. At that point, use the vos +examine command to determine how much space the volume is +occupying. Then issue the fs setquota command to set a quota +that is slightly larger. +
```
   
+   # fs setquota /afs/.cellname/sysname/usr/afsws  0
+   
+
```
+

Copy the contents of the indicated directories from the CD-ROM +into the +/afs/cellname/sysname/usr/afsws +directory. +

   
+   # cd /afs/.cellname/sysname/usr/afsws
+   
+   # cp -rp /cdrom/sysname/bin  .
+   
+   # cp -rp /cdrom/sysname/etc  .
+   
+   # cp -rp /cdrom/sysname/include  .
+   
+   # cp -rp /cdrom/sysname/lib  .
+   
+

Issue the fs setacl command to set the ACL on each directory +appropriately. To comply with the terms of your AFS License agreement, +you must prevent unauthorized users from accessing AFS software. To +enable access for locally authenticated users only, set the ACL on the +etc, include, and lib subdirectories to grant +the l and r permissions to the +system:authuser group rather than the +system:anyuser group. The +system:anyuser group must retain the l and +r permissions on the bin subdirectory to enable +unauthenticated users to access the klog binary. To ensure +that unauthorized users are not accessing AFS software, check periodically +that the ACLs on these directories are set properly. +
```
     
+   # cd /afs/.cellname/sysname/usr/afsws
+   
+   # fs setacl  -dir etc include lib  -acl  system:authuser rl  \
+              system:anyuser none
+   
+
```
+
Perform this step on the new client machine even if you have +performed the previous steps on another machine. Create +/usr/afsws on the local disk as a symbolic link to the directory +/afs/cellname/@sys/usr/afsws. You can +specify the actual system name instead of @sys if you wish, but the +advantage of using @sys is that it remains valid if you upgrade +this machine to a different system type. +
```
   
+   # ln -s /afs/cellname/@sys/usr/afsws  /usr/afsws
+   
+
```
+
(Optional) To enable users to issue commands from the AFS +suites (such as fs) without having to specify a pathname to their +binaries, include the /usr/afsws/bin and /usr/afsws/etc +directories in the PATH environment variable you define in each user's +shell initialization file (such as .cshrc). +
(Optional) If you believe it is helpful to your users to access +the AFS documents in a certain format via a local disk directory, create +/usr/afsdoc on the local disk as a symbolic link to the +documentation directory in AFS +(/afs/cellname/afsdoc/format_name). +
+
```
   
+   # ln -s /afs/cellname/afsdoc/format_name /usr/afsdoc
+
```
+
An alternative is to create a link in each user's home directory to +the /afs/cellname/afsdoc/format_name +directory. +
(Optional) If working on the local machine, remove the AFS +binaries from the temporary location. They are now accessible in the +/usr/afsws directory. +
```
   
+   # cd  /tmp
+   
+   # rm  klog  fs  vos
+     
+
```
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartUnix/auqbg008.htm b/doc/html/QuickStartUnix/auqbg008.htm new file mode 100644 index 0000000..be194b3 --- /dev/null +++ b/doc/html/QuickStartUnix/auqbg008.htm @@ -0,0 +1,213 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

Appendix A. Building AFS from Source Code

This chapter describes how to build AFS from source +code. + + + + + +

Loading the Source Files

Working on an AFS client machine, perform these steps to +load the AFS source tree from the AFS Source Distribution. +

Create and mount a volume for housing the AFS source tree. These +instructions name the volume src.afs and mount it at the +/afs/cellname/afs/src directory. +
Setting the -maxquota argument to 0 (zero) sets an +unlimited quota on the volume, which enables you to copy all of the files into +the volume without exceeding its quota. If you wish, you can set the +volume's quota to a finite value after you complete the copying +operation. At that point, use the vos examine command to +determine how much space the volume is occupying. Then issue the +fs setquota command to set a quota that is slightly larger. +
```
   
+   # vos create <machine name> <partition name> src.afs -maxquota 0 
+   
+   # cd /afs/.cellname
+   
+   # mkdir afs
+   
+   # fs mkmount afs/src src.afs
+   
+   # vos release root.cell
+   
+   # fs checkvolumes
+   
+
```
+
On the local /cdrom directory, mount the CD-ROM that contains +the AFS source files. For instructions on mounting CD-ROMs (either +locally or remotely via NFS), consult the operating system +documentation. + + +

Copy the source files from the CD-ROM into the newly created +volume. +

   
+   # cd /cdrom/src
+   
+   # cp -rp  *  /afs/.cellname/afs/src
+   
+

+ + + +

Compiling AFS Binaries Using the washtool Program

The AFS distribution includes the washtool +program for managing a hierarchy of software development projects. The +program builds project trees for program editing, compilation, and +installation. +

Create a subdirectory under the +/afs/.cellname/afs directory for each +system type for which you will build AFS binaries. Creating and +mounting a volume for each system type is recommended, but you can also simply +use the mkdir command. If you create a new volume, grant it +an unlimited quota to avoid running out of space during the build +process. +
```
   
+   # cd /afs/.cellname/afs    
+
```
+
If creating a new volume: +
```
   
+   # vos create <machine name> <partition name> sysname -maxquota 0
+   
+   # fs mkmount sysname sysname    
+
```
+
If not creating a new volume: +
```
    
+   # mkdir sysname
+   
+
```
+
In the directory for each system type, create subdirectories called +dest, dest/bin, and obj. If you plan +to use the @sys variable in pathnames that refer to these +directories, then you must use the conventional system names listed in the +IBM AFS Release Notes. +
```
   
+   # cd sysname
+   
+   # mkdir dest 
+   
+   # mkdir dest/bin 
+   
+   # mkdir obj
+   
+
```
+

Create the indicated directories and symbolic links in the +/afs/.cellname/afs directory. +

   
+   # cd /afs/.cellname/afs
+   
+   # ln -s  @sys/dest  dest
+   
+   # ln -s  @sys/obj  obj
+   
+   # ln -s  .  PARENT
+   
+   # ln -s  src/Makefile  Makefile   
+

The following is an example directory listing for the +/afs/.cellname/afs directory after +completing the preceding steps. It includes two example system +types. +

   
+   lrwxr-xr-x admin   12 Jun 18 11:26 Makefile->src/Makefile
+   lrwxr-xr-x admin    1 Jun 18 11:26 PARENT -> .
+   lrwxr-xr-x admin    9 Jun 18 11:25 dest -> @sys/dest
+   lrwxr-xr-x admin    8 Jun 18 11:25 obj -> @sys/obj
+   drwxrwxrwx admin 4096 Jun 18 11:24 rcs
+   drwxrwxrwx admin 2048 Jun 18 11:27 rs_aix42
+   drwxrwxrwx admin 2048 Jun 18 11:10 src
+   drwxrwxrwx admin 2048 Jun 18 11:27 sun4x_56
+   
+

(Optional) By default, the build procedure writes its results +into a destination directory for each system type called +/afs/.cellname/afs/sysname/dest. +To write the results to a different destination directory, create a link from +the dest directory to it. +
```
   
+   # cd /afs/.cellname/afs/sysname
+   
+   # ln -s full_path_of_alternate_directory dest
+   
+
```
+ + +
For each system type you plan to build, copy the binary for the +washtool program to the directory specified in the AFS +Makefile, which is +/afs/cellname/afs/sysname/dest/bin. +If you prefer to store the program in a different directory, you can use the +WASHTOOL variable on the make command line as described in Step 6. +
If there is a volume that houses the AFS binaries for each system type (as +recommended), the conventional location for the washtool binary is +the +/afs/cellname/sysname/usr/afsws/bin +directory. Use the following instruction to copy it. +
```
   
+   # cd  /afs/cellname/sysname/usr/afsws/bin
+   
+   # cp  washtool  /afs/.cellname/afs/sysname/dest/bin   
+
```
+
Otherwise, mount the (binary) AFS CD-ROM for this system type on the local +/cdrom directory, and copy the washtool binary directly +from it. +
```
   
+   # cd  /cdrom/sysname/bin
+   
+   # cp  washtool  /afs/.cellname/afs/sysname/dest/bin
+   
+
```
+ + + + + + +
Working in the +/afs/.cellname/afs directory on a +machine of the system type for which you are building AFS, issue the make +install command. Set the SYS_NAME variable to the appropriate +system type name. +
If the washtool binary is not in the conventional directory +(/afs/cellname/afs/sysname/dest/bin), +set the WASHTOOL variable to the alternate full pathname of the binary. +
```
  
+   # cd /afs/.cellname/afs
+  
+   # make SYS_NAME=sysname [WASHTOOL=alternate_washtool_directory] install
+   
+
```
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartUnix/auqbg009.htm b/doc/html/QuickStartUnix/auqbg009.htm new file mode 100644 index 0000000..83977c5 --- /dev/null +++ b/doc/html/QuickStartUnix/auqbg009.htm @@ -0,0 +1,2644 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

Index

+Special Characters
+A +B +C +D +E +F +H +I +K +L +M +N +O +P +Q +R +S +T +U +V +W +

+Special Characters + +

/ as start to file and directory names + +

see alphabetized entries without initial slash +(2238) +

+A + +

access + +

to local and foreign cells +(2670) +

to root and admin accounts +(2680) +

access control list (ACL), setting +(2602) +

activating AFS init. script (see entry installing) +(2585) +

adding + +

entries to BosConfig file + +

database server machine +(2887) +

first AFS machine +(2426) +

server machine after first +(2806) +

new db-server machine to CellServDB files +(2879) +

admin account + +

adding + +

to system:administrators group +(2482) +

to UserList file +(2468) +

controlling access to +(2681) +

creating +(2433) +

setting ADMIN flag on Auth. DB entry +(2458) +

afs (/afs) directory + +

as root of AFS filespace +(3027) +

creating + +

client machine +(3026) +

first AFS machine +(2552) +

server machine after first +(2849) +

AFS Binary Distribution +(2214) +

AFS cache (see entry: cache) +(3011) +

afs entry in Authentication Database +(2434) +

afs file + +

AFS initialization file +(3064), (3067), (3070), (3077), (3081) +

afsd options file (Linux) +(3033) +

AFS filespace + +

configuring top levels +(2592) +

controlling access by root superuser +(2682) +

deciding how to configure +(2223) +

enabling access to foreign cells +(2671) +

root at /afs directory +(3028) +

AFS initialization script + +

adding to machine startup sequence + +

client machine +(3058) +

first AFS machine +(2582) +

server machine after first +(2852) +

running + +

client machine +(3054) +

first AFS machine +(2558) +

server machine after first +(2853) +

setting afsd parameters + +

client machine +(3042) +

first AFS machine +(2553) +

server machine after first +(2850) +

verifying on first AFS machine +(2557) +

AFS kernel extensions + +

on client machine + +

AIX +(2937) +

Digital UNIX +(2946) +

HP-UX +(2955) +

IRIX +(2964) +

Linux +(2978) +

Solaris +(2987) +

on first AFS machine + +

AIX +(2250) +

Digital UNIX +(2267) +

HP-UX +(2285) +

IRIX +(2303) +

Linux +(2330) +

Solaris +(2343) +

on server machine after first + +

AIX +(2708) +

Digital UNIX +(2720) +

HP-UX +(2732) +

IRIX +(2746) +

Linux +(2763) +

Solaris +(2771) +

AFS login + +

on client machine + +

AIX +(2941) +

Digital UNIX +(2950) +

HP-UX +(2959) +

IRIX +(2975) +

Linux +(2982) +

Solaris +(2991) +

on file server machine + +

AIX +(2262) +

Digital UNIX +(2279) +

HP-UX +(2297) +

IRIX +(2322) +

Linux +(2338) +

Solaris +(2355) +

AFS server partition + +

configuring on first AFS machine + +

AIX +(2254) +

Digital UNIX +(2271) +

HP-UX +(2289) +

IRIX +(2318) +

Linux +(2334) +

Solaris +(2351) +

configuring on server machine after first + +

AIX +(2712) +

Digital UNIX +(2724) +

HP-UX +(2736) +

IRIX +(2757) +

Linux +(2767) +

Solaris +(2779) +

mounted on /vicep directory +(2242) +

protecting during operating system upgrade +(2212) +

afsclient variable (IRIX) + +

client machine +(3074) +

first AFS machine +(2568) +

server machine after first +(2861) +

afsd + +

command in AFS init. script +(3037) +

options file (Linux) +(3030) +

afsml variable (IRIX) + +

client machine +(2967) +

first AFS machine +(2310) +

server machine after first +(2749) +

afsserver variable (IRIX) + +

first AFS machine +(2571) +

server machine after first +(2864) +

afsxnfs variable (IRIX) + +

client machine +(2970) +

first AFS machine +(2313) +

server machine after first +(2752) +

AIX + +

AFS initialization script + +

on add'l server machine +(2857) +

on client machine +(3059) +

on first AFS machine +(2564), (2586) +

AFS kernel extensions + +

on add'l server machine +(2710) +

on client machine +(2939) +

on first AFS machine +(2252) +

AFS login + +

on client machine +(2943) +

on file server machine +(2264) +

AFS server partition + +

on add'l server machine +(2714) +

on first AFS machine +(2256) +

editing /etc/vfs file +(3052) +

fsck program + +

on add'l server machine +(2718) +

on first AFS machine +(2260) +

Authentication Database +(2435) +

Authentication Server + +

starting + +

first AFS machine +(2408) +

new db-server machine +(2883) +

authorization checking (disabling) + +

first AFS machine +(2366) +

server machine after first +(2802) +

+B + +

background reading list +(2199) +

Backup Server + +

starting + +

first AFS machine +(2412) +

new db-server machine +(2888) +

stopping +(2914) +

Basic OverSeer Server (see entry BOS Server) +(2362) +

binaries + +

storing AFS in volume +(2632), (3087) +

storing system in volumes +(2667) +

Binary Distribution (AFS) +(2215) +

binary distribution machine +(2517) +

bos commands + +

addhost +(2875) +

addkey +(2470) +

adduser +(2463) +

create +(2432) +

delete +(2918) +

listhosts +(2402) +

listkeys +(2474) +

removehost +(2906) +

restart + +

on first AFS machine +(2484) +

on new db-server machine +(2895) +

on removed db-server machine +(2923) +

setcellname +(2400) +

shutdown +(2563) +

status +(2500) +

stop +(2911) +

BOS Server + +

checking mode bits on AFS directories +(2683) +

starting + +

first AFS machine +(2363) +

server machine after first +(2799) +

BosConfig file + +

adding entries + +

database server machine +(2886) +

first AFS machine +(2425) +

server machine after first +(2805) +

removing entries +(2919) +

bosserver command +(2381) +

building + +

AFS extensions into kernel (see entry incorporating AFS kernel extensions) +(2241) +

AFS from source +(3104) +

buserver process (see entry Backup Server) +(2413) +

+C + +

cache + +

choosing size +(3015) +

configuring + +

client machine +(3022) +

first AFS machine +(2545) +

server machine after first +(2842) +

requirements +(3014) +

Cache Manager + +

client machine +(3046) +

first AFS machine +(2549) +

server machine after first +(2846) +

cacheinfo file +(3018) +

CD-ROM + +

copying AFS binaries into volume +(2643) +

copying AFS documentation from +(2660) +

copying client files from + +

client machine +(2998) +

first AFS machine +(2527) +

server machine after first +(2830) +

copying server files from + +

first AFS machine +(2369) +

server machine after first +(2785) +

copying source files from +(3101) +

creating /cdrom directory + +

client machine +(2929) +

first AFS machine +(2228) +

server machine after first +(2693) +

packaging of AFS Binary Distribution +(2216) +

cdrom directory + +

client machine +(2930) +

first AFS machine +(2229) +

server machine after first +(2694) +

cell + +

enabling access to foreign +(2669) +

improving security +(2677) +

initializing security mechanisms +(2439) +

cell name + +

choosing +(2222) +

defining during installation of first machine +(2382) +

setting in client ThisCell file + +

client machine +(3001) +

first AFS machine +(2530) +

server machine after first +(2833) +

setting in server ThisCell file + +

first AFS machine +(2384) +

server machine after first +(2834) +

symbolic link for abbreviated +(2613) +

CellServDB file (client) + +

adding entry + +

for foreign cell +(2674) +

for new db-server machine +(2881) +

creating + +

on client machine +(3006) +

on first AFS machine +(2539) +

on server machine after first +(2840) +

removing entry +(2903) +

required format +(2541) +

CellServDB file (server) + +

adding entry for new db-server machine +(2878) +

creating + +

on first AFS machine +(2393) +

on server machine after first +(2793) +

displaying entries +(2403) +

removing entry +(2908) +

client cache (see entry: cache) +(3010) +

client machine + +

/cdrom directory +(2931) +

/usr/vice/etc directory +(2934) +

AFS initialization script +(3055) +

AFS kernel extensions + +

on AIX +(2938) +

on Digital UNIX +(2947) +

on HP-UX +(2956) +

on IRIX +(2965) +

on Linux +(2979) +

on Solaris +(2988) +

AFS login + +

on AIX +(2942) +

on Digital UNIX +(2951) +

on HP-UX +(2960) +

on IRIX +(2976) +

on Linux +(2983) +

on Solaris +(2992) +

afsd command parameters +(3043) +

afsd options file (Linux) +(3036) +

Cache Manager +(3048) +

cache size and location +(3025) +

cell membership +(3003) +

CellServDB file + +

adding entry +(2882) +

creating during initial installation +(3009) +

removing entry +(2904) +

copying client files to local disk +(2999) +

requirements for installation +(2206) +

ThisCell file +(3004) +

vfs file (AIX) +(3053) +

clock synchronization +(2523) +

commands + +

afsd +(3038) +

bos addhost +(2876) +

bos addkey +(2469) +

bos adduser +(2462) +

bos create +(2431) +

bos delete +(2917) +

bos listhosts +(2401) +

bos listkeys +(2473) +

bos removehost +(2907) +

bos restart + +

on first AFS machine +(2483) +

on new db-server machine +(2894) +

on removed db-server machine +(2922) +

bos setcellname +(2399) +

bos shutdown +(2562) +

bos status +(2499) +

bos stop +(2910) +

bosserver +(2380) +

fs checkvolumes +(2581), (2628) +

fs examine +(2622) +

fs mkmount +(2607) +

fs newcell +(2676) +

fs setacl +(2601) +

fs setquota +(2637) +

kas (interactive) +(2446) +

kas create +(2449) +

kas examine +(2453) +

kas quit +(2459) +

kas setfields +(2456) +

klog +(2576) +

make +(3107) +

pts adduser +(2479) +

pts createuser +(2476) +

tokens +(2578) +

vos addsite +(2617) +

vos create + +

root.afs volume +(2501) +

root.cell volume +(2604) +

src.afs volume +(3095) +

volume for AFS binaries +(2635) +

volume for AFS documentation +(2657) +

vos release +(2623) +

vos syncserv +(2508) +

vos syncvldb +(2506) +

washtool +(3105) +

compiling AFS from source +(3103) +

configuring + +

AFS filespace (top levels) +(2593) +

AFS server partition on first AFS machine + +

AIX +(2253) +

Digital UNIX +(2270) +

HP-UX +(2288) +

IRIX +(2317) +

Linux +(2333) +

Solaris +(2350) +

AFS server partition on server machine after first + +

AIX +(2711) +

Digital UNIX +(2723) +

HP-UX +(2735) +

IRIX +(2756) +

Linux +(2766) +

Solaris +(2778) +

cache + +

client machine +(3023) +

first AFS machine +(2546) +

server machine after first +(2843) +

Cache Manager + +

client machine +(3047) +

first AFS machine +(2550) +

server machine after first +(2847) +

copying + +

AFS binaries into volume +(2642) +

AFS documentation from CD-ROM +(2659) +

client files to local disk + +

client machine +(3000) +

first AFS machine +(2529) +

server machine after first +(2832) +

server files to local disk + +

first AFS machine +(2373) +

server machine after first +(2784) +

source files from CD-ROM +(3100) +

creating + +

/cdrom directory + +

client machine +(2932) +

first AFS machine +(2231) +

server machine after first +(2696) +

/usr/afs directory + +

first AFS machine +(2234) +

server machine after first +(2699) +

/usr/afs/bin directory + +

first AFS machine +(2371) +

server machine after first +(2702) +

/usr/afs/etc directory + +

first AFS machine +(2372) +

server machine after first +(2789) +

/usr/vice/etc directory + +

client machine +(2935) +

first AFS machine +(2237) +

server machine after first +(2705) +

admin account in Authentication Database +(2437) +

afs entry in Authentication Database +(2436) +

CellServDB file (client) + +

client machine +(3008) +

first AFS machine +(2540) +

server machine after first +(2841) +

CellServDB file (server) + +

first AFS machine +(2394) +

server machine after first +(2790) +

mount point +(2609) +

read/write mount point +(2616) +

root.afs volume +(2505) +

root.cell volume +(2596) +

server encryption key + +

Authentication Database +(2452) +

KeyFile file +(2471) +

src.afs volume +(3099) +

symbolic link + +

for abbreviated cell name +(2611) +

to AFS binaries +(2647) +

UserList file entry +(2467) +

volume + +

for AFS source +(3091) +

for AFS binaries +(2630), (3085) +

for AFS documentation +(2652) +

for system binaries +(2665) +

+D + +

database server machine + +

entry in client CellServDB file + +

for foreign cell +(2673) +

for new db-server machine +(2880) +

on client machine +(3007) +

on first AFS machine +(2537) +

on server machine after first +(2839) +

removing +(2902) +

entry in server CellServDB file + +

for new db-server machine +(2877) +

on first AFS machine +(2390) +

on server machine after first +(2794) +

removing +(2909) +

installing + +

additional +(2872) +

first +(2405) +

removing db-server processes from BosConfig file +(2921) +

removing from service +(2898) +

requirements for installation +(2869) +

starting database server processes +(2885) +

stopping database server processes +(2912) +

defining + +

cell name during installation of first machine +(2383) +

first AFS machine as database server +(2398) +

replication site for volume +(2620) +

Digital UNIX + +

AFS initialization script + +

on add'l server machine +(2858) +

on client machine +(3063) +

on first AFS machine +(2565), (2587) +

AFS login + +

on client machine +(2952) +

on file server machine +(2281) +

AFS server partition + +

on add'l server machine +(2726) +

on first AFS machine +(2273) +

AFS-modified kernel + +

on add'l server machine +(2722) +

on client machine +(2948) +

on first AFS machine +(2269) +

fsck program + +

on add'l server machine +(2730) +

on first AFS machine +(2277) +

directories + +

/afs +(3029) +

/usr/afsdoc +(2656) +

/usr/afsws +(2634), (3089) +

/usr/vice/cache +(3021) +

/vicepxx (see entry AFS server partition) +(2248) +

disabling authorization checking + +

first AFS machine +(2367) +

server machine after first +(2803) +

disk cache (see entry: cache) +(3012) +

displaying + +

CellServDB file (server) entries +(2404) +

server encryption key + +

Authentication Database +(2455) +

KeyFile file +(2475) +

documentation, creating volume for AFS +(2654) +

+E + +

enabling AFS login + +

client machine + +

AIX +(2940) +

Digital UNIX +(2949) +

HP-UX +(2958) +

IRIX +(2974) +

Linux +(2981) +

Solaris +(2990) +

file server machine + +

AIX +(2261) +

Digital UNIX +(2278) +

HP-UX +(2296) +

IRIX +(2321) +

Linux +(2337) +

Solaris +(2354) +

encryption files + +

in AFS Binary Distribution +(2217) +

encryption key (see entry server encryption key) +(2445) +

environment variables (see entry: variables) +(3045) +

etc/init.d/afs (see entry: afs file) +(3073) +

etc/rc.afs (see entry: rc.afs file) +(3062) +

etc/rc.d/init.d/afs (see entry: afs file) +(3079) +

etc/sysconfig/afs (see entry: afs file) +(3034) +

etc/vfs file +(3051) +

+F + +

File Server + +

first AFS machine +(2487) +

server machine after first +(2818) +

file server machine + +

requirements for installation +(2204) +

see entries first AFS machine; file server machine, additional +(2218) +

file server machine, additional + +

/cdrom directory +(2695) +

/usr/afs directory +(2698) +

/usr/afs/bin directory +(2701) +

/usr/afs/etc directory +(2788) +

/usr/vice/etc directory +(2704) +

AFS initialization script +(2854) +

AFS kernel extensions + +

on AIX +(2709) +

on Digital UNIX +(2721) +

on HP-UX +(2733) +

on IRIX +(2747) +

on Linux +(2764) +

Solaris +(2772) +

AFS login (see entry for first AFS machine) +(2706) +

AFS server partition + +

on AIX +(2713) +

on Digital UNIX +(2725) +

on HP-UX +(2737) +

on IRIX +(2758) +

on Linux +(2768) +

on Solaris +(2780) +

afsd command parameters +(2851) +

authorization checking (disabling) +(2804) +

BOS Server +(2801) +

Cache Manager +(2848) +

cache size and location +(2845) +

cell membership, defining + +

for client processes +(2837) +

for server processes +(2796) +

client functionality +(2829) +

copying + +

client files to local disk +(2831) +

server files to local disk +(2786) +

File Server +(2820) +

fs process +(2827) +

fsck program + +

on AIX +(2717) +

on Digital UNIX +(2729) +

on HP-UX +(2741) +

on IRIX +(2743) +

on Linux +(2760) +

on Solaris +(2776) +

runntp process +(2816) +

server functionality +(2782) +

ThisCell file (client) +(2836) +

ThisCell file (server) +(2798) +

Update Server client portion +(2810) +

Update Server server portion +(2813) +

Volume Server +(2823) +

file systems clean-up script (Solaris) + +

client machine +(2996) +

file server machine +(2360) +

files + +

afs + +

AFS initialization file +(3065), (3068), (3071), (3078), (3082) +

afsd options file (Linux) +(3032) +

AFS initialization (see entry: AFS initialization script) +(3040) +

AFS source +(3094) +

afsd options file (Linux) +(3031) +

BosConfig +(2427) +

cacheinfo +(3019) +

CellServDB (client) +(2543) +

CellServDB (server) +(2395) +

index.htm +(2663) +

KeyFile +(2443) +

protecting during operating system upgrade +(2213) +

rc.afs +(3061) +

ThisCell (client) +(2536) +

ThisCell (server) +(2389) +

UserList +(2466) +

vfs (AIX) +(3049) +

fileserver process (see entry File Server) +(2488) +

filespace (see entry AFS filespace) +(2224) +

first AFS machine + +

fsck program + +

on AIX +(2259) +

/cdrom directory +(2230) +

/usr/afs directory +(2233) +

/usr/vice/etc directory +(2236) +

AFS initialization script + +

activating +(2584) +

running/verifying +(2559) +

AFS kernel extensions + +

on AIX +(2251) +

on Digital UNIX +(2268) +

on HP-UX +(2286) +

on IRIX +(2304) +

on Linux +(2331) +

on Solaris +(2344) +

AFS login + +

on AIX +(2263) +

on Digital UNIX +(2280) +

on HP-UX +(2298) +

on IRIX +(2323) +

on Linux +(2339) +

on Solaris +(2356) +

AFS server partition + +

on AIX +(2255) +

on Digital UNIX +(2272) +

on HP-UX +(2290) +

on IRIX +(2319) +

on Linux +(2335) +

on Solaris +(2352) +

afsd command parameters +(2554) +

Authentication Server +(2409) +

authorization checking (disabling) +(2368) +

Backup Server +(2415) +

BOS Server +(2365) +

Cache Manager +(2551) +

cache size and location +(2548) +

cell membership, defining + +

for client processes +(2533) +

for server processes +(2391) +

CellServDB file (client) +(2544) +

CellServDB file (server) +(2396) +

client functionality + +

installing +(2525) +

removing +(2686) +

completion of installation +(2556) +

copying + +

AFS binaries into volume +(2644) +

AFS documentation from CD-ROM +(2661) +

client files to local disk +(2528) +

server files to local disk +(2374) +

defining + +

as binary distribution machine +(2514) +

as database server +(2397) +

as system control machine +(2515) +

File Server, fs process +(2490) +

fsck program + +

on Digital UNIX +(2276) +

on HP-UX +(2294) +

on IRIX +(2307) +

on Linux +(2327) +

on Solaris +(2348) +

Protection Server +(2419) +

roles +(2198) +

runntp process +(2520) +

Salvager +(2498) +

server functionality +(2226) +

subdirectories of /usr/afs +(2370) +

ThisCell file (client) +(2532) +

ThisCell file (server) +(2386) +

Update Server server portion +(2513) +

VL Server +(2423) +

Volume Server +(2494) +

foreign cell, enabling access +(2668) +

fs commands + +

checkvolumes +(2580), (2627) +

examine +(2621) +

mkmount +(2606) +

newcell +(2675) +

setacl +(2600) +

setquota +(2638) +

fs process + +

first AFS machine +(2496) +

server machine after first +(2825) +

fsck program + +

on first AFS machine + +

AIX +(2258) +

Digital UNIX +(2275) +

HP-UX +(2293) +

IRIX +(2306) +

Linux +(2326) +

Solaris +(2347) +

on server machine after first + +

AIX +(2716) +

Digital UNIX +(2728) +

HP-UX +(2740) +

IRIX +(2744) +

Linux +(2761) +

Solaris +(2775) +

+H + +

HP-UX + +

AFS initialization script + +

on add'l server machine +(2859) +

on client machine +(3069) +

on first AFS machine +(2566), (2588) +

AFS login + +

on client machine +(2961) +

on file server machine +(2299) +

AFS server partition + +

on add'l server machine +(2738) +

on first AFS machine +(2291) +

AFS-modified kernel + +

on add'l server machine +(2734) +

on client machine +(2957) +

on first AFS machine +(2287) +

fsck program + +

on add'l server machine +(2742) +

on first AFS machine +(2295) +

+I + +

incorporating AFS kernel extensions + +

client machine + +

AIX +(2936) +

Digital UNIX +(2945) +

HP-UX +(2954) +

IRIX +(2963) +

Linux +(2977) +

Solaris +(2986) +

first AFS machine + +

AIX +(2249) +

Digital UNIX +(2266) +

HP-UX +(2284) +

IRIX +(2302) +

Linux +(2329) +

Solaris +(2342) +

server machine after first + +

AIX +(2707) +

Digital UNIX +(2719) +

HP-UX +(2731) +

IRIX +(2745) +

Linux +(2762) +

Solaris +(2770) +

index.htm file +(2662) +

initializing + +

cell security mechanisms +(2440) +

server process (see entry starting or server's name) +(2428) +

installing + +

AFS initialization script + +

client machine +(3057) +

first AFS machine +(2583) +

server machine after first +(2856) +

client functionality + +

client machine +(2927) +

first AFS machine +(2526) +

server machine after first +(2828) +

database server machine + +

additional +(2874) +

first +(2407) +

file server machine after first +(2689) +

first AFS machine +(2220) +

server functionality + +

first AFS machine +(2227) +

server machine after first +(2783) +

instructions + +

client machine +(2926) +

database server machine, installing additional +(2873) +

database server machine, installing first +(2406) +

database server machine, removing +(2899) +

file server machine after first +(2688) +

first AFS machine +(2219) +

interactive mode for kas + +

entering +(2448) +

quitting +(2461) +

invoking AFS init. script (see entry running) +(2561) +

IRIX + +

AFS initialization script + +

on add'l server machine +(2860) +

on client machine +(3072) +

on first AFS machine +(2567), (2589) +

AFS kernel extensions + +

on client machine +(2966) +

on first AFS machine +(2309) +

on server machine after first +(2748) +

AFS login +(2324) +

AFS server partition + +

on add'l server machine +(2759) +

on first AFS machine +(2320) +

AFS-modified kernel + +

on add'l server machine +(2755) +

on client machine +(2973) +

on first AFS machine +(2316) +

afsclient variable + +

client machine +(3076) +

first AFS machine +(2570) +

server machine after first +(2863) +

afsml variable + +

client machine +(2969) +

first AFS machine +(2312) +

server machine after first +(2751) +

afsserver variable + +

first AFS machine +(2573) +

server machine after first +(2866) +

afsxnfs variable + +

client machine +(2972) +

first AFS machine +(2315) +

server machine after first +(2754) +

fsck program replacement not necessary +(2308) +

+K + +

kas commands + +

create +(2450) +

examine +(2454) +

interactive mode, entering +(2447) +

quit +(2460) +

setfields +(2457) +

kaserver process (see entry Authentication Server) +(2410) +

Kerberos +(2430) +

kernel extensions (see entry AFS kernel extensions) +(2239) +

key (see entry server encryption key) +(2444) +

KeyFile file + +

first AFS machine +(2442) +

server machine after first +(2792) +

klog command +(2577) +

+L + +

licensing requirements +(2646) +

Linux + +

AFS initialization script + +

on add'l server machine +(2867) +

on client machine +(3080) +

on first AFS machine +(2574), (2590) +

AFS kernel extensions + +

on add'l server machine +(2765) +

on client machine +(2980) +

on first AFS machine +(2332) +

AFS login + +

on client machine +(2984) +

on file server machine +(2340) +

AFS server partition + +

on add'l server machine +(2769) +

on first AFS machine +(2336) +

afsd options file +(3035) +

fsck program replacement not necessary +(2328) +

loading AFS kernel extensions (see entry incorporating) +(2240) +

logical volume (see entry AFS server partition) +(2244) +

+M + +

make command +(3108) +

memory cache (see entry: cache) +(3013) +

mode bits on local AFS directories +(2684) +

mount point +(2608) +

+N + +

naming conventions for AFS server partition +(2246) +

NTPD + +

first AFS machine +(2521) +

server machine after first +(2817) +

+O + +

operating system upgrades +(2210) +

OPTIONS variable in AFS initialization file +(3039) +

overview + +

completing installation of first machine +(2555) +

general installation requirements +(2202) +

installing additional database server machine +(2871) +

installing client functionality on first machine +(2524) +

installing client machine +(2928) +

installing server functionality on first AFS machine +(2225) +

installing server machine after first +(2692) +

removing database server machine +(2901) +

+P + +

PAM + +

on HP-UX + +

client machine +(2962) +

file server machine +(2300) +

on Linux + +

client machine +(2985) +

file server machine +(2341) +

on Solaris + +

client machine +(2994) +

file server machine +(2358) +

partition (see entry AFS server partition) +(2243) +

PATH environment variable for users +(2649) +

Pluggable Authentication Module (see entry PAM) +(2301) +

Protection Database +(2478) +

Protection Server + +

starting + +

first AFS machine +(2416) +

new db-server machine +(2890) +

stopping +(2915) +

pts commands + +

adduser +(2480) +

createuser +(2477) +

ptserver process (see entry Protection Server) +(2417) +

+Q + +

quota for volume +(2639) +

+R + +

rc.afs file (AFS init. file for AIX) +(3060) +

read/write mount point for root.afs volume +(2614) +

reading list for background information +(2200) +

releasing replicated volume +(2626) +

removing + +

client functionality from first AFS machine +(2687) +

database server machine from service +(2900) +

entries from BosConfig File +(2920) +

entry from CellServDB file +(2905) +

replacing fsck program + +

first AFS machine + +

AIX +(2257) +

Digital UNIX +(2274) +

HP-UX +(2292) +

Solaris +(2346) +

not necessary on IRIX +(2305) +

not necessary on Linux +(2325) +

server machine after first + +

AIX +(2715) +

Digital UNIX +(2727) +

HP-UX +(2739) +

Solaris +(2774) +

replicating volumes +(2599) +

requirements + +

AFS server partition name and location +(2245) +

cache +(3016) +

CellServDB file format (client version) +(2542) +

client machine +(2207) +

database server machine +(2870) +

file server machine (additional) +(2691) +

file server machine (general) +(2205) +

first AFS machine +(2221) +

general +(2203) +

protecting binaries per AFS license +(2645) +

restarting server process + +

on first AFS machine +(2485) +

on new db-server machine +(2896) +

on removed db-server machine +(2924) +

roles for first AFS machine +(2197) +

root superuser + +

as installer's login identity +(2201) +

controlling access +(2679) +

root.afs volume + +

creating +(2503) +

read/write mount point +(2615) +

replicating +(2597) +

root.cell volume + +

creating and replicating +(2594) +

mounting for foreign cells in local filespace +(2672) +

running AFS init. script + +

client machine +(3056) +

first AFS machine +(2560) +

server machine after first +(2855) +

runntp process + +

first AFS machine +(2518) +

server machine after first +(2814) +

+S + +

Salvager (salvager process) + +

first AFS machine +(2495) +

server machine after first +(2824) +

sbin/init.d/afs (see entry: afs file) +(3066) +

scripts + +

AFS initialization (see entry: AFS initialization script) +(3041) +

file systems clean-up (Solaris) + +

client machine +(2997) +

file server machine +(2361) +

secondary authentication system (AIX) + +

client machine +(2944) +

server machine +(2265) +

security + +

improving +(2678) +

initializing cell-wide +(2438) +

Security Integration Architecture (see entry SIA) +(2283) +

server encryption key + +

in Authentication Database +(2451) +

in KeyFile file +(2472) +

server machine after first (see entry: file server machine, additional) +(2690) +

server process + +

restarting + +

on first AFS machine +(2486) +

on new db-server machine +(2897) +

on removed db-server machine +(2925) +

see also entry for each server's name +(2429) +

setting + +

ACL +(2603) +

cache size and location + +

client machine +(3024) +

first AFS machine +(2547) +

server machine after first +(2844) +

cell name in client ThisCell file + +

client machine +(3002) +

first AFS machine +(2531) +

server machine after first +(2835) +

cell name in server ThisCell file + +

first AFS machine +(2385) +

server machine after first +(2797) +

volume quota +(2641) +

SIA (Digital UNIX) + +

client machine +(2953) +

file server machine +(2282) +

Solaris + +

AFS initialization script + +

on add'l server machine +(2868) +

on client machine +(3083) +

on first AFS machine +(2575), (2591) +

AFS kernel extensions + +

on add'l server machine +(2773) +

on client machine +(2989) +

on first AFS machine +(2345) +

AFS login + +

on client machine +(2993) +

on file server machine +(2357) +

AFS server partition + +

on add'l server machine +(2781) +

on first AFS machine +(2353) +

file systems clean-up script + +

on client machine +(2995) +

on file server machine +(2359) +

fsck program + +

on add'l server machine +(2777) +

on first AFS machine +(2349) +

source (AFS) + +

compiling +(3102) +

storing in AFS volume +(3093) +

src.afs volume +(3097) +

starting + +

Authentication Server + +

first AFS machine +(2411) +

new db-server machine +(2884) +

Backup Server + +

first AFS machine +(2414) +

new db-server machine +(2889) +

BOS Server + +

first AFS machine +(2364) +

server machine after first +(2800) +

File Server + +

first AFS machine +(2489) +

server machine after first +(2819) +

fs process + +

first AFS machine +(2497) +

server machine after first +(2826) +

Protection Server + +

first AFS machine +(2418) +

new db-server machine +(2891) +

runntp process + +

first AFS machine +(2519) +

server machine after first +(2815) +

Update Server client portion +(2809) +

Update Server server portion + +

first AFS machine +(2512) +

server machine after first +(2812) +

VL Server + +

first AFS machine +(2422) +

new db-server machine +(2893) +

Volume Server + +

first AFS machine +(2493) +

server machine after first +(2822) +

stopping + +

database server processes +(2913) +

storing + +

AFS binaries in volumes +(2629), (3084) +

AFS documentation in volumes +(2651) +

AFS source in volume +(3090) +

system binaries in volumes +(2664) +

supported system types +(2209) +

symbolic link + +

for abbreviated cell name +(2612) +

to AFS binaries from local disk +(2648) +

system control machine +(2516) +

system types supported +(2208) +

system:administrators group +(2481) +

SYS_NAME variable for washtool command +(3111) +

+T + +

ThisCell file (client) + +

client machine +(3005) +

first AFS machine +(2535) +

server machine after first +(2838) +

ThisCell file (server) + +

first AFS machine +(2388) +

server machine after first +(2795) +

time synchronization +(2522) +

tokens command +(2579) +

+U + +

UNIX mode bits on local AFS directories +(2685) +

upclient process +(2808) +

Update Server + +

starting client portion +(2807) +

starting server portion + +

first AFS machine +(2510) +

server machine after first +(2811) +

upgrading the operating system +(2211) +

upserver process (see entry Update Server) +(2511) +

UserList file + +

first AFS machine +(2465) +

server machine after first +(2791) +

usr/afs directory + +

first AFS machine +(2232) +

server machine after first +(2697) +

usr/afs/bin directory + +

first AFS machine +(2375) +

server machine after first +(2700) +

usr/afs/db directory +(2377) +

usr/afs/etc directory + +

first AFS machine +(2376) +

server machine after first +(2787) +

usr/afs/etc/CellServDB file (see entry CellServDB file (server)) +(2392) +

usr/afs/etc/KeyFile (see entry KeyFile file) +(2441) +

usr/afs/etc/ThisCell (see entry ThisCell file (server)) +(2387) +

usr/afs/etc/UserList (see entry UserList file) +(2464) +

usr/afs/local directory +(2378) +

usr/afs/local/BosConfig (see entry BosConfig file) +(2424) +

usr/afs/logs directory +(2379) +

usr/afsdoc directory +(2655) +

usr/afsws directory +(2633), (3088) +

usr/vice/cache directory +(3020) +

usr/vice/etc directory + +

client machine +(2933) +

first AFS machine +(2235) +

server machine after first +(2703) +

usr/vice/etc/cacheinfo (see entry: cacheinfo file) +(3017) +

usr/vice/etc/CellServDB (see entry CellServDB file (client)) +(2538) +

usr/vice/etc/ThisCell (see entry ThisCell file (client)) +(2534) +

+V + +

variables + +

afsclient (IRIX) + +

client machine +(3075) +

first AFS machine +(2569) +

server machine after first +(2862) +

afsml (IRIX) + +

client machine +(2968) +

first AFS machine +(2311) +

server machine after first +(2750) +

afsserver (IRIX) + +

first AFS machine +(2572) +

server machine after first +(2865) +

afsxnfs (IRIX) + +

client machine +(2971) +

first AFS machine +(2314) +

server machine after first +(2753) +

OPTIONS (in AFS initialization file) +(3044) +

PATH, setting for users +(2650) +

SYS_NAME for washtool command +(3110) +

WASHTOOL +(3109) +

vfs file +(3050) +

vicepxx directory (see entry AFS server partition) +(2247) +

VL Server (vlserver process) + +

starting + +

first AFS machine +(2420) +

new db-server machine +(2892) +

stopping +(2916) +

volserver process (see entry Volume Server) +(2492) +

volume + +

creating + +

root.afs +(2504) +

root.cell +(2595) +

src.afs +(3098) +

defining replication site +(2619) +

for AFS binaries +(2631), (3086) +

for AFS documentation +(2653) +

for AFS source +(3092) +

for system binaries +(2666) +

mounting +(2610) +

releasing replicated +(2625) +

replicating root.afs and root.cell +(2598) +

setting quota +(2640) +

Volume Location Server (see entry VL Server) +(2421) +

Volume Server + +

first AFS machine +(2491) +

server machine after first +(2821) +

vos commands + +

addsite +(2618) +

create + +

root.afs volume +(2502) +

root.cell volume +(2605) +

src.afs volume +(3096) +

volume for AFS binaries +(2636) +

volume for AFS documentation +(2658) +

release +(2624) +

syncserv +(2509) +

syncvldb +(2507) +

+W + +

washtool command +(3106) +

WASHTOOL variable +(3112) +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartWindows/awqbg000.htm b/doc/html/QuickStartWindows/awqbg000.htm new file mode 100755 index 0000000..ae88d5a --- /dev/null +++ b/doc/html/QuickStartWindows/awqbg000.htm @@ -0,0 +1,43 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

+AFS for Windows
+Quick Beginnings
+

Version 3.6 +

Document Number SC09-4564-00 +

CT6Q8NA +

First Edition (April 2000) +

This edition applies to: +

IBM AFS for Windows, 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. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartWindows/awqbg002.htm b/doc/html/QuickStartWindows/awqbg002.htm new file mode 100755 index 0000000..1333341 --- /dev/null +++ b/doc/html/QuickStartWindows/awqbg002.htm @@ -0,0 +1,64 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

IBM AFS for Windows Quick Beginnings
+

Introduction +

Document Overview + +

Audience +

Organization +

Installing AFS for Windows + +

AFS for Windows Components +

Installation Options +

Upgrading From an Earlier Version +

To Install AFS for Windows +

Changes Made to Your System +

AFS for Windows Documentation + +

The Online Documentation Directory +

The CD-ROM Documentation Directory +

Online Help +

Configuring AFS for Windows + +

To Configure the AFS Client +

To Configure the AFS Client as an AFS Light Gateway +

To Configure AFS Light +

To Configure the AFS Server +

To Configure the AFS Control Center +

Uninstalling AFS for Windows + +

Reinstalling and Upgrading +

Uninstallation Prerequisites +

To Uninstall AFS for Windows +

Changes Made to Your System +

Index
+

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartWindows/awqbg003.htm b/doc/html/QuickStartWindows/awqbg003.htm new file mode 100755 index 0000000..7914c7f --- /dev/null +++ b/doc/html/QuickStartWindows/awqbg003.htm @@ -0,0 +1,1203 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

IBM AFS for Windows Quick Beginnings

Introduction

+ + +

AFS^(R) is an enterprise file system that provides consistent +file access by way of a shared filespace. By joining the local file +systems of several File Server machines, AFS presents a single filespace +independent of machine boundaries. Files are stored on different +machines in the computer network but are accessible from all machines across +the enterprise. +

IBM AFS for Windows^(R), version 3.6 extends the full +capabilities of AFS to Microsoft^(R) Windows operating +systems. +

Document Overview

+ +This document summarizes installation prerequisites, provides detailed +instructions on how to install, configure, and uninstall AFS for Windows, and +outlines the changes made to your system during the installation and +uninstallation processes. This document also describes the +documentation provided with AFS for Windows. +

Audience

+ +This document provides information for system administrators and users +responsible for the installation and configuration of the products included in +AFS for Windows. This document assumes that system administrators are +familiar with system administration in general and that users are familiar +with the basic terms and concepts of the Microsoft Windows operating +systems. +

Organization

This document has the following organization: +

Installing AFS for Windows outlines installable combinations of AFS components, +describes the procedure for installing the products that are included in AFS +for Windows, and lists the changes that the installation process makes to your +system. +
AFS for Windows Documentation presents the various types of documentation that are +provided with AFS for Windows and discusses procedures for accessing this +documentation. +
Configuring AFS for Windows describes the procedures for configuring the products that +are included in AFS for Windows. +
Uninstalling AFS for Windows outlines uninstallation prerequisites, describes the +procedure for uninstalling the products that are included in AFS for Windows, +and lists the changes that the uninstallation process makes to your +system. +

Installing AFS for Windows

This section outlines installable combinations of AFS components, +describes the procedure for installing AFS for Windows, and lists the changes +that the installation process makes to your system. +

AFS for Windows Components

+ +AFS for Windows, version 3.6 includes the following components: +

+ + + +AFS Server +
The AFS Server runs AFS server processes and includes the AFS Server +Configuration Wizard to facilitate setup. +
+ + + +AFS Control Center +
The AFS Control Center includes two powerful graphical user interface (GUI) +tools to assist AFS system administrators in AFS cell administration: +the AFS Server Manager and the AFS Account Manager. +
+ + + +AFS Client +
The AFS Client provides direct access to the AFS filespace, enabling users +to manage files and directories in AFS. The AFS Client includes the AFS +Light Gateway. +
+ + + +AFS Light +
AFS Light provides access to the AFS filespace via an AFS Light Gateway +machine, enabling users to manage files and directories in AFS. +
+ +AFS Supplemental Documentation +
AFS Supplemental Documentation provides additional AFS system +administration information and includes the following documents: +IBM AFS Administration Guide and IBM AFS Administration +Reference. +

Installation Options

+ + + +You can install the components of AFS for Windows in various combinations, +based on your Windows operating system. Refer to the IBM AFS for +Windows Release Notes for details on the specific software requirements +for each AFS for Windows component. Note that if you are installing the +AFS Server, you must also install the AFS Client, unless the AFS Client, +version 3.6 is already installed on the machine. Follow the +installation procedure described in To Install AFS for Windows regardless of the components you are installing. +
Note: + + + + + +You have the option of altering the AFS for Windows setup program to disable +all but the client component. Such a client-only setup program renders +users unable to install any components other than the AFS Client. To +perform a client-only installation, create the file setup.co +in the same directory as the other installation files; the setup program +then only allows the AFS Client to be installed. Note that the contents +of the setup.co file are irrelevent. Follow the +installation procedure described in To Install AFS for Windows regardless of the type of installation you are +performing. +
+

Upgrading From an Earlier Version

+ + + +On a Windows NT machine, it is not necessary to uninstall the +components of AFS for Windows for the purpose of upgrading the software; +you can install this release of AFS for Windows on your system +without removing or unconfiguring your existing software. To +upgrade AFS for Windows, follow the installation procedure described in To Install AFS for Windows. During the installation process, the +previous-version AFS component is upgraded and the AFS configuration +information is preserved. +

On a Windows 95 or Windows 98 machine, you must uninstall the +previously-installed AFS Light component, as described in To Uninstall AFS for Windows, before upgrading AFS Light. +

Note that the AFS for Windows installation tool does not allow a +user to install AFS components that have different version numbers. If +you have more than one AFS for Windows component installed on your machine, +you cannot update one component without updating all of the other components +as well. +

To Install AFS for Windows

+ + + + + + + +

Before installing AFS for Windows, refer to your IBM AFS for Windows +Release Notes for a detailed description of the installation +prerequisites. If you are running any other Windows applications, it is +recommended that you exit from them before installing AFS for Windows. +

Insert the AFS for Windows installation disk into your CD-ROM +drive. +
Run the AFS for Windows setup program by using one of the +following methods: +
- From the Start menu, select Run. Type +drive:\setup where drive is +the drive letter of your CD-ROM drive. Click OK. +
- In the Windows Explorer, select your CD-ROM drive, and +double-click the setup.exe program. +
+
The Welcome dialog box appears. Select the Next button +to continue with the installation process. +

The Select Components dialog box appears. +

In the Components box, select the AFS for Windows components +that you want to install or upgrade. See Installation Options for information on the various combinations of components +that can be installed on a Windows machine. Note that if you are +installing the AFS Server, you must also select to install (or upgrade) the +AFS Client, unless the AFS Client, version 3.6 is already installed on +your system. +

The Destination Folder box indicates the default drive and +directory in which the selected components will be installed. The +default drive is the drive where Windows is installed. The default +directory on that drive is \Program Files\Ibm\Afs. To select +another drive, directory, or both, select the Browse button. +

Note:

If you are upgrading from a previous-version of AFS for Windows or +reinstalling AFS for Windows, the installation directory that you choose must +be the same as the installation directory that was used by the +previously-installed version. +

Select the Next button to continue with the installation +process. +

The application files for the selected AFS for Windows components are +installed on your system. When the installation process finishes, the +Setup Complete dialog box appears, indicating that you must restart your +system before you can use the installed AFS products. Select Yes, +I want to restart my computer now, and then select the Finish +button. Your system is shut down and then restarted. +
Installation of AFS for Windows is complete. +

Changes Made to Your System

+ +This section describes the changes that are made to your system by installing +each AFS for Windows component. The information in this section is +based upon the default installation settings. +

Changes made to your system by installing the AFS Client

Installing the AFS Client for Windows NT makes the following changes to +your system: +

Creates a Start menu program group named IBM AFS +with the following program applications: +
+
The Documentation program entry allows access to the AFS online +documentation set that is provided with AFS for Windows. +
The Client program subgroup enables users to access the AFS +Client property box and the AFS Client Online Help. +
+
Adds the AFS Menu to the Windows NT Explorer's context menu. +
Creates a documentation directory and places the IBM AFS for Windows +Quick Beginnings and the IBM AFS for Windows Release Notes +online documents in the directory, which is located at \Program +Files\Ibm\Afs\Documentation. +
Adds AFS Credentials to the Startup program +group. The AFS Client icon is displayed in the taskbar at +startup. +
Creates the installation directories in which the setup program installs +AFS binaries, icons, and help files. The default directories are +\Program Files\Ibm\Afs\Client\Program and \Program +Files\Ibm\Afs\Common. +
Registers the AFS Client as a service. +
Installs the AFS Client Configuration utility and adds the AFS Client +Configuration icon to the Control Panel by placing the +afs_cpa.cpl file in the +\WindowsDefault\system32 directory, where +WindowsDefault is your Windows directory. +
Places the afsdcell.ini file in your Windows directory +and in the \Program Files\Ibm\Afs\Common directory. If you +have upgraded from a previous-version AFS Client, the AFS Client cell database +(afsdcell.ini) in the Windows directory is not +replaced. +
Modifies the Windows NT Registry by adding entries relevant to the AFS +Client. +

Changes made to your system by installing AFS Light

Installing AFS Light for Windows 95 and Windows 98 makes the following +changes to your system: +

Creates a program group named IBM AFS with the following +program applications: +
+
The Documentation program entry allows access to the AFS online +documentation set that is provided with AFS for Windows. +
The Light program subgroup enables users to access the AFS +Light property box and the AFS Light Online Help. +
+
Adds the AFS Menu to the Windows Explorer's context menu. +
Creates a documentation directory and places the IBM AFS for Windows +Quick Beginnings and the IBM AFS for Windows Release Notes +online documents in the directory, which is located at \Program +Files\Ibm\Afs\Documentation. +
Creates the installation directories in which the setup program installs +AFS binaries, icons, and help files. The default directories are +\Program Files\Ibm\Afs\Client\Program and \Program +Files\Ibm\Afs\Common. +
Installs the AFS Light Configuration utility and adds the AFS Light +Configuration icon to the Control Panel by placing the +afs_cpa.cpl file in the +\WindowsDefault\system directory, where +WindowsDefault is your Windows directory. +
Places the afsdcell.ini file in your Windows directory +and in the \Program Files\Ibm\Afs\Common directory. +
Modifies the Windows Registry by adding entries relevant to AFS +Light. +

Changes made to your system by installing the AFS Server

Installing the AFS Server for Windows NT makes the following changes to +your system: +

Creates a Start menu program group named IBM AFS +with the following program applications: +
+
The Documentation program entry allows access to the AFS online +documentation set that is provided with AFS for Windows. +
The Server program subgroup enables users to access the AFS +Server Quick-Start Wizard. +
+
Creates a documentation directory and places the IBM AFS for Windows +Quick Beginnings and the IBM AFS for Windows Release Notes +online documents in the directory, which is located at \Program +Files\Ibm\Afs\Documentation. +
Creates the installation directories in which the setup program installs +AFS binaries, icons, and help files. The default directories are +\Program Files\Ibm\Afs\Server\usr\afs\bin and \Program +Files\Ibm\Afs\Common. +
Registers the AFS Server as a service. +
Installs the AFS Server Configuration application and adds the AFS +Server Configuration icon to the Control Panel by placing the +afsserver.cpl file in the +\WindowsDefault\system32 directory, where +WindowsDefault is your Windows directory. +
Modifies the Windows NT Registry by adding entries relevant to the AFS +Server. +

Changes made to your system by installing the AFS Control Center

Installing the AFS Control Center for Windows NT makes the following +changes to your system: +

Creates a Start menu program group named IBM AFS +with the following program applications: +
+
The Documentation program entry allows access to the AFS online +documentation set that is provided with AFS for Windows. +
The Control Center program subgroup enables users to access the +Account Manager and the Server Manager. +
+
Creates a documentation directory and places the IBM AFS for Windows +Quick Beginnings and the IBM AFS for Windows Release Notes +online documents in the directory, which is located at \Program +Files\Ibm\Afs\Documentation. +
Creates the installation directories in which the setup program installs +AFS binaries, icons, and help files. The default directories are +\Program Files\Ibm\Afs\Control Center and \Program +Files\Ibm\Afs\Common. +
Installs the AFS Control Center Properties utility and adds the AFS +Control Center icon to the Control Panel by placing the +afs_cpa.cpl file in the +\WindowsDefault\system32 directory, where +WindowsDefault is your Windows directory. This icon is added +to the Control Panel if only the AFS Control Center is installed on your +system. +
Places the afsdcell.ini file in your Windows directory +and in the \Program Files\Ibm\Afs\Common directory. +
Modifies the Windows NT Registry by adding entries relevant to the AFS +Control Center. +

Changes made to your system by installing the AFS Supplemental Documentation

Installing the AFS Supplemental Documentation makes the following +changes to your system: +

Creates a Start menu program group named IBM AFS +with a program entry named Documentation. +
The following system administration documents are installed on the +machine: IBM AFS Administration Guide and IBM AFS +Administration Reference. These documents are added to the online +documentation directory, which is located at \Program +Files\Ibm\Afs\Documentation. The IBM AFS for Windows Quick +Beginnings and the IBM AFS for Windows Release Notes online +documents are also installed in the documentation directory. +
Modifies the Windows NT Registry by adding entries relevant to the AFS +Supplemental Documentation. +

AFS for Windows Documentation

This section describes the documentation that is provided with AFS for +Windows and details the procedures for accessing this documentation. +

The Online Documentation Directory

+ + +

Regardless of the components you install on your system, a documentation +directory is created. The default location is \Program +Files\Ibm\Afs\Documentation. This directory includes the IBM +AFS for Windows Quick Beginnings and IBM AFS for Windows Release +Notes. These same documents are available from the Documentation +index accessed from the Documentation entry in the Start +menu. +

If you install the AFS Supplemental Documentation, then the documentation +directory also includes the following documents: IBM AFS +Administration Guide and IBM AFS Administration +Reference. These same documents are available from the +Documentation index accessed from the Documentation entry in the +Start menu. +

To access the online documentation directory:

From the Start menu, choose Programs, then choose +IBM AFS, then choose Documentation. +
Select the document that you want to view. +

The CD-ROM Documentation Directory

+ + +

The AFS for Windows CD-ROM contains a documentation directory. This +directory includes the following documentation: IBM AFS for Windows +Quick Beginnings, IBM AFS for Windows Release Notes, IBM +AFS Administration Guide, and IBM AFS Administration +Reference. The documentation is provided in HTML and PDF +formats. +

To access the CD-ROM documentation directory:

Insert the AFS for Windows CD-ROM into your machine's CD-ROM +drive. +
Follow one of the paths listed below. Note that CD is +the drive letter of your CD-ROM drive. +
- For HTML documentation, follow the path +CD:\Documentation\Html. +
- For PDF documentation, follow the path +CD:\Documentation\Pdf. +
+

Online Help

+ + +

Online help is installed along with each AFS for Windows component. +The online help documentation describes the features available from each +component. Use the Help menus and Help buttons +located on most dialog boxes to access the online help. You can get +help on topics by browsing the contents page, using the index to locate +topics, and using Find, the online help search engine. +

Configuring AFS for Windows

+ + +This section details the configuration procedure for each of the components of +AFS for Windows. You must configure the components on your system +before you can use AFS. +

To Configure the AFS Client

+ + +

Note:

If you intend to configure the AFS Server on your Windows NT system, you do +not need to configure the AFS Client. The AFS Client is configured +automatically when the AFS Server is configured. In addition, if you +upgraded to this version of AFS for Windows from a previous-version AFS +Client, configuration information is preserved. You do not need to +reconfigure the AFS Client. +

From the Start menu, choose Settings, then choose +Control Panel. +
Double-click the AFS Client Configuration icon. The AFS +Client Configuration utility opens, displaying the General +tab. +
In the Cell Name box, enter the name of the AFS cell in which +the machine is to be a client. +
Select the AFS Cells tab. If the cell in which the +machine is to be a client is not listed in the list of AFS cells, choose the +Add button. The New Cell dialog box opens. Enter the +cell name in the AFS Cell box and a short description in the +Description box. +
Choose the Add button. The Add Server dialog box +opens. In the Server Name box, enter the name of a Volume +Location Server in the selected cell. Choose OK to close the +Add Server dialog box. Repeat this process, adding information for all +Volume Location Servers in the cell. (If you do not know the names of +the Volume Location Servers in the AFS cell, consult your AFS system +administrator.) After all server information has been entered, choose +OK to close the New Cell dialog box. +
Select the General tab and choose the Start Service +button to start the AFS Client service. +
Select the Drive Letters tab. To map a drive letter on +the Windows NT machine to the AFS filespace, choose the Add +button. The Map Drive Letter dialog box opens. +
In the Drive Letter box, select the drive to be mapped to the +AFS filespace or accept the default. In the AFS +Path box, indicate the AFS location to which you want to map the +selected drive, for example, /afs. If desired, enter a +description of the AFS drive mapping in the Description box. +Choose OK to connect the drive to the specified place in the AFS +filespace. +
Choose OK to close the AFS Client Configuration utility. +
The AFS Client is now configured in the selected AFS cell and the AFS +filespace can be accessed via the selected drive mapping in the Windows NT +Explorer. +

To Configure the AFS Client as an AFS Light Gateway

+ + + +

You can configure the AFS Client on your Windows NT machine to serve as an +AFS Light Gateway. Your AFS Client, configured as an AFS Light Gateway, +makes it possible for AFS Light users to access the AFS filespace. +

Configure the AFS Client as detailed in To Configure the AFS Client. +
From the Start menu, choose Settings, then choose +Control Panel. +
Double-click the AFS Client Configuration icon. The AFS +Client Configuration utility opens, displaying the General +tab. +
Select the Provide an AFS Light Gateway option. +
Choose OK. +
- If the AFS Client service is running, a message box appears, informing you +that the service must be restarted. Choose Yes to restart +the AFS Client service and enable the AFS Light Gateway. +
- If the AFS Client service is stopped, a message box appears, informing you +that you must start the AFS Client service. Choose Yes to +start the AFS Client service and enable the AFS Light Gateway. +
+
+ +Add cell entries to your AFS Light Gateway's cell database. Note +that in order for an AFS Light user to access a cell, an entry for the cell +must exist in both the AFS Light cell database and the AFS Light Gateway cell +database. Incorrect or missing information about a cell in the gateway +machine's cell database renders light client machines unable to access +files. +
To add an entry to the cell database: +
Access the AFS Cells tab from the AFS Light Configuration +utility and choose the Add button. The New Cell dialog box +opens. Enter the cell name in the AFS Cell box and a short +description in the Description box. +
Choose the Add button. The Add Server dialog box +opens. In the Server Name box, enter the name of a Volume +Location Server in the selected cell. Choose OK to close the +Add Server dialog box. Repeat this process, adding information for all +Volume Location Servers in the cell. (If you do not know the names of +the Volume Location Servers in the AFS cell, consult your AFS system +administrator.) After all server information has been entered, choose +OK to close the New Cell dialog box. +

+ + + +The Windows NT machine is now configured as an AFS Light Gateway. Once +configured as an AFS Light Gateway, your AFS Client machine must be able to +authenticate AFS Light users in a Windows context. This authentication +can be achieved via a domain user account or via synchronized +machine user accounts. A domain user account is a user +account in a Windows domain. A machine user account is a user account +that is valid only on a particular host machine. +

When the AFS Light Gateway is configured into a Windows domain, the AFS +Light user must log onto either a domain user account in the domain to which +the gateway belongs or a machine user account with the same username and +password as that of a domain user account in the gateway domain. +

If machine user accounts are employed, then these accounts must be +synchronized on the AFS Light Gateway and AFS Light machines. A user +must log onto an AFS Light machine with the same username and password as that +of a machine user account that is defined on the AFS Light Gateway +machine. +

To Configure AFS Light

+ + +

AFS Light accesses the AFS filespace via an AFS Light Gateway. +Before configuring AFS Light, you must have a Windows NT machine running the +AFS Client and configured as an AFS Light Gateway. See To Configure the AFS Client as an AFS Light Gateway for more information. +

From the Start menu, choose Settings, then choose +Control Panel. +
Double-click the AFS Light Configuration icon. The AFS +Light Configuration utility opens, displaying the General +tab. + + +

In the Gateway box, enter the name of a Windows NT machine that +is configured as an AFS Light Gateway and click Connect Now. +The name of the gateway machine is the gateway's NetBIOS service name, in +the form mach-afs, where mach is the +host computer name up to a maximum of 11 characters. AFS Light must be +able to resolve this service name in order to communicate with the gateway +machine. Name resolution can be achieved by adding the gateway's +NetBIOS service name to the client's LMHOSTS file or to the appropriate +DNS or WINS servers. If the AFS Light machine and its AFS Light Gateway +machine reside on the same subnet, then no additional configuration is +required. +

AFS Light automatically becomes a member of the same cell as its AFS Light +Gateway. The name of the cell is displayed in the Cell Name +box. +
Note: If the AFS Light Gateway machine is in the same domain as the AFS Light +machine and the hostname of the gateway machine in this domain is +xyz-pc, you can specify the computer name in the Gateway +box as either xyz-pc or +xyz-pc.xcompany.com. +
+

Select the AFS Cells tab. If the cell to which the +machine belongs is not listed in the list of AFS cells, choose the +Add button. The New Cell dialog box opens. Enter the +cell name in the AFS Cell box and a short description in the +Description box. +
Choose the Add button. The Add Server dialog box +opens. In the Server Name box, enter the name of a Volume +Location Server in the selected cell. Choose OK to close the +Add Server dialog box. Repeat this process, adding information for all +Volume Location Servers in the cell. (If you do not know the names of +the Volume Location Servers in the AFS cell, consult your AFS system +administrator.) After all server information has been entered, choose +OK to close the New Cell dialog box. +
Note that an identical entry must exist in the AFS Light Gateway's +cell database (afsdcell.ini file) in order for the AFS Light +user to authenticate to the cell. See To Configure the AFS Client as an AFS Light Gateway for more information on synchronizing the gateway +machine's cell database with your light client's cell +database. +
Select the Drive Letters tab. To map a drive letter on +the Windows machine to the AFS filespace, choose the Add +button. The Map Drive Letter dialog box opens. +
In the Drive Letter box, select the drive to be mapped to the +AFS filespace or accept the default. In the AFS +Path box, indicate the AFS location to which you want to map the +selected drive, for example, /afs. If desired, enter a +description of the AFS drive mapping in the Description box. +Choose OK to connect the drive to the specified place in the AFS +filespace. +
Choose OK to close the AFS Light Configuration utility. +
AFS Light is now configured in the specified AFS cell and the AFS filespace +can be accessed via the drive mapping in the Windows Explorer. +

To Configure the AFS Server

+ + +

The configuration process starts the services needed to run the AFS Server +and sets up AFS partitions on your Windows NT machine. Using the AFS +Configuration Wizard, you can quickly configure the AFS Server as either the +first server in a new AFS cell or as a server in an existing AFS cell. +Note that if you have upgraded to this version of the AFS Server, +previous-version configuration information is preserved; you do not need +to reconfigure the server. +

+ +To configure the AFS Server as the first AFS Server in a cell: +

From the Start menu, choose Programs, then choose +IBM AFS, then choose Server, and then choose +Configuration Wizard. The AFS Server Quick-Start +Wizard opens. +
Choose the Next button. The Cell and Server Information +dialog box appears. +
Choose the This will be the first server in a new AFS cell +option. +
In the Cell Name box, enter a name for the new AFS cell. +
The following constraints apply to the form of an internet domain name that +can be used as the name of an AFS cell: +
- The cell name must be unique in order to distinguish your AFS cell from +all others in the AFS global namespace. +
- The cell name can contain as many as 64 characters; however, shorter +names are recommended. +
- The cell name must include only lowercase characters, numbers, +underscores, dashes, and periods to ensure portability between different +operating system types. +
- The cell name can include any numbers or letters, which are conventionally +separated by periods. +
- The cell name must end in a suffix that indicates the type of institution +to which it belongs. Some of the standard suffixes are +.com, for business and other commercial organizations, +.edu, for educational institutions such as universities, +.gov, for government institutions, and +.mil, for military institutions. +
+
In the Password box, enter the character string to serve as the +password for the AFS Server principal account in the cell +(afs). All AFS Servers obtain AFS tokens as this principal, +and the Authentication Server's Ticket Granting Service (TGS) module uses +this password to encrypt the server tickets that AFS Clients present to +servers during mutual authentication. +
In the Verify password box, retype the initial AFS password for +the AFS Server principal account for this cell to confirm the password +selection. +
Choose the Next button. The Administrative Information +dialog box appears. +
In the Name box, enter a username to serve as a generic AFS +administrative account for this cell (generally, admin.) +
+ +Use of a generic administrative account means that you do not need to grant +privileges to each system administrator. Instead, each administrator +knows the name and password of this generic administrative account and uses +this identity to authenticate to AFS when performing tasks that require +administrative privileges. +
In the Password box, enter a character string to serve as the +password for the AFS administrative account. +
In the Verify password box, retype the password for the AFS +administrative account to confirm the password selection. +
Specify the AFS User ID (UID) to assign to the AFS administrative +account: +
- (Recommended) To automatically assign the next available UID to the AFS +administrative account, choose the Use the next available AFS UID +option. +
- To assign a specific UID to the AFS administrative account, choose the +Use this AFS ID option and enter the desired UID in the entry +box. +
  Note: It is not generally recommended that you assign a specific UID to a new AFS +account, unless you need to make the AFS UID match an existing UNIX +UID. +
  +
+
Choose the Next button. The File Service dialog box +appears. +
+ +AFS File Servers deliver requested files and data from the server to AFS +Clients. File Servers store files and data, handle requests for +copying, moving, creating, and deleting files and directories, and keep track +of status information about each file and directory on the server. +
Because you are configuring the first AFS Server in a new cell, the File +Service must be configured on the server, and will be configured +automatically. +
Choose the Next button. The Database Service dialog box +appears. +
+ +Every AFS cell must contain at least one Database Server. Each Database +Server runs the Database processes that maintain the AFS databases: the +Authentication Database, the Protection Database, the Volume Location +Database, and optionally the Backup Database. +
Because you are configuring the first AFS Server in a new cell, the +Database Service must be configured on the server, and will be configured +automatically. +
Choose the Next button. The Backup Server dialog box +appears. +
+ +A Backup Server maintains the Backup Database where information related to the +Backup system is stored. The Backup Server enables the AFS system +administrator to back up data in the AFS filespace from volumes to +tape. The data can then be restored from tape in the event that it is +lost from the file system (for example, if a system or disk failure causes +data to be lost). +
Choose the Yes, configure as a Backup Server option if you want +to configure this AFS Server as a Backup Server. If you do not want to +configure this AFS Server as a Backup Server, choose the No, do not +configure as a Backup Server option. +
Note: If the Backup Server is configured on any Database Server in the cell, it +must be configured on all Database Servers in the cell. +
+
Choose the Next button. The AFS Partition dialog box +appears. +
+ +Every AFS File Server must have at least one partition designated exclusively +to storing AFS volumes, and all AFS volumes must reside on partitions that +have been designated as AFS partitions. On a Windows NT machine, only +NTFS volumes can be designated as AFS partitions. In addition, AFS +partitions can be created only on NTFS volumes that are empty (or contain only +the Windows NT Recycle Bin). +
Because you are configuring the first AFS Server in a new cell, you must +designate an AFS partition on the server. +

In the list of NTFS volumes, choose the volume you want to designate as an +AFS partition. In the AFS Partition Name box, enter the last +part of the partition name. +

Note:

There can exist up to 256 AFS partitions on an AFS Server. By +convention, each partition is named /vicepx, where +x is one or two lowercase letters of the English alphabet. +AFS partitions can be named /vicepa, /vicepb, and so on +up to /vicepz. Additional partitions can be named +/vicepaa through vicepaz and so on up to +/vicepiv. +

It is strongly recommended that you use the NTFS volume drive letter as the +last letter of the partition name. +

Choose the Next button. The Root AFS Volumes dialog box +appears. +
+ + + +The root AFS volumes are two volumes that every AFS cell must include in its +file system. They are named: +
- root.afs, for the volume corresponding to the top +(/afs) level of the AFS filespace +
- root.cell, for the volume mounted just below +/afs at the cell's name (for example, +/afs/yourcompany.com in the +yourcompany.com cell) +
+
Because you are configuring the first AFS Server in a new cell, the +cell's root volumes must be created on the server, and will be created +automatically during the configuration of the server. +
Choose the Next button. The Replication dialog box +appears. +
+ +If you want to be able to take advantage of the replication capabilities of +AFS, the AFS root volumes must be replicated. The replication process +creates one or more read-only copies of an AFS volume, and distributes these +copies to one or more other sites (AFS partitions and servers). +Replication increases system efficiency and improves data availability by +making the contents of an AFS volume accessible on one or more AFS File Server +machines. +
Because you are configuring the first AFS Server in a new cell, the +cell's root volumes must be replicated on the server, and will be +replicated automatically during the configuration of the server. +

Choose the Next button. The System Control Service +dialog box appears. +

+ +In cells running the domestic version of AFS for Windows, the System Control +Server distributes new versions of AFS Server configuration information to all +AFS servers. It is generally recommended that you designate the first +server in an AFS cell as the System Control Server. (Cells running the +international version of AFS for Windows do not use the System Control Server +to distribute system configuration files.) +
Note: The role of System Control Server can later be assigned to a different server +machine if desired. However, depending on the number of AFS servers in +the cell, the process of assigning the role to another machine can be very +time-consuming. +
+

To configure this AFS Server as the System Control Server for the AFS +cell, choose the Configure as the System Control Server +option. If you do not want to configure this AFS Server as the System +Control Server for the AFS cell, choose the Do not configure as the +System Control Server option. +
Choose the Next button. The Configure the System dialog +box appears. +
A list of the steps that will be taken to configure this AFS Server is +displayed, enabling you to review the steps before starting the actual +configuration process. +
Note: To return to a previous step to review or modify your selections, choose the +Back button. +
+
To begin configuration of the AFS Server on this machine, choose the +Configure button. The AFS Server is configured according to +your specifications. The progress bar at the bottom of the dialog box +indicates the steps in progress. A message box appears indicating that +configuration is complete. +

+ +To configure the AFS Server into an existing AFS cell: +

From the Start menu, choose Programs, then choose +IBM AFS, then choose Server, and then choose +Configuration Wizard. The AFS Server Quick-Start +Wizard opens. +
Choose the Next button. The Cell and Server Information +dialog box appears. +
Choose the Make this host a server in an existing AFS cell +option. +
In the Cell Name box, enter the name of the AFS cell to which +you want to add the new AFS Server. +
Choose the Next button. The Administrative Information +dialog box appears. +
In the Name box, enter the username of the AFS administrative +account, for example admin, or the username of an AFS user account +with administrative privileges. +
In the Password box, enter the password for the AFS +administrative account or the AFS user account with administrative privileges +entered in the Name box. +
In the AFS Server box, enter the hostname of a running AFS +Server in this AFS cell. AFS configuration information will be +retrieved from the server for use in configuring this new AFS Server. +
Choose the Next button. The File Service dialog box +appears. +
+ +AFS File Servers deliver requested files and data from the server to AFS +Clients. File Servers store files and data, handle requests for +copying, moving, creating, and deleting files and directories, and keep track +of status information about each file and directory on the server. +
To configure this AFS Server as a File Server, choose the Yes, +configure as a File Server option. If you do not want to +configure this AFS Server as a File Server, choose the No, do not +configure as a File Server option. +
Choose the Next button. The Database Service dialog box +appears. +
+ +Every AFS cell must contain at least one Database Server. Each Database +Server runs the Database processes that maintain the AFS databases: the +Authentication Database, the Protection Database, the Volume Location +Database, and optionally the Backup Database. +
To configure this AFS Server as a Database Server, choose the Yes, +configure as a Database Server option. If there is a System +Control Server in the AFS cell to which you are adding the server, enter its +hostname in the System Control Server box. AFS configuration +information (for example, the list of AFS Database Servers maintained in the +CellServDB file on each AFS Server machine) will be updated by this +server. If you do not want to configure this AFS Server as a Database +Server, choose the No, do not configure as a Database Server +option. +

Choose the Next button. The Backup Server dialog box +appears. +

+ +A Backup Server maintains the Backup Database where information related to the +Backup system is stored. The Backup Server enables the AFS system +administrator to back up data in the AFS filespace from volumes to +tape. The data can then be restored from tape in the event that it is +lost from the file system (for example, if a system or disk failure causes +data to be lost). +
Note: The Backup Server can only be configured on a machine that is configured as a +Database Server. Also, if the Backup Server is configured on any +Database Server in the cell, it must be configured on all Database +Servers in the cell. +
+

Choose the Yes, configure as a Backup Server option if you want +to configure this AFS Server as a Backup Server. If you do not want to +configure this AFS Server as a Backup Server, choose the No, do not +configure as a Backup Server option. +

Choose the Next button. The AFS Partition dialog box +appears. +

If you are configuring this AFS Server as a File Server, you must specify +an NTFS volume to designate as an AFS partition. Every AFS File Server +must have at least one partition designated exclusively to storing AFS +volumes, and all AFS volumes must reside on partitions that have been +designated as AFS partitions. On a Windows NT machine, only NTFS +volumes can be designated as AFS partitions. In addition, AFS +partitions can be created only on NTFS volumes that are empty (or contain only +the Windows NT Recycle Bin). +

To designate a volume as an AFS partition, choose the Yes, create a +partition option. In the list of NTFS volumes, choose the volume +that you want to designate as an AFS partition. In the AFS +Partition Name box, enter the last part of the partition name. +
Note: There can exist up to 256 AFS partitions on an AFS Server. By +convention, each partition is named /vicepx, where +x is one or two lowercase letters of the English alphabet. +AFS partitions can be named /vicepa, /vicepb, and so on +up to /vicepz. Additional partitions can be named +/vicepaa through vicepaz and so on up to +/vicepiv. +
+

It is strongly recommended that you use the NTFS volume drive letter as the +last letter of the partition name. +

If you do not want to designate a volume as an AFS partition, choose the +No, do not create a partition option. +

Choose the Next button. The Root AFS Volumes dialog box +appears. +
The root AFS volumes are two volumes that every AFS cell must include in +its file system. They are named: +
- root.afs, for the volume corresponding to the top +(/afs) level of the AFS filespace +
- root.cell, for the volume mounted just below +/afs at the cell's name (for example, +/afs/yourcompany.com in the +yourcompany.com cell) +
+ +Because you are adding this AFS Server to an existing AFS cell, the root AFS +volumes already exist in the cell, and the AFS Configuration Wizard indicates +that you do not need to create the root volumes. +
Note: If for some reason the root AFS volumes do not yet exist in this AFS cell, +you can choose the Yes, create the root volumes option to create +the root volumes on this AFS Server. +
+

Choose the Next button. The Replication dialog box +appears. +

If you want to be able to take advantage of the replication capabilities of +AFS, the AFS root volumes must be replicated. The replication process +creates one or more read-only copies of an AFS volume, and distributes these +copies to one or more other sites (AFS partitions and servers). +Replication increases system efficiency and improves data availability by +making the contents of an AFS volume accessible on one or more AFS File Server +machines. +

Because you are adding this AFS Server to an existing AFS cell, the root +AFS volumes are probably already replicated, and the AFS Server Configuration +Wizard indicates that you do not need to replicate the root AFS +volumes. +
Note: If for some reason the root AFS volumes are not yet replicated in this AFS +cell, you can choose the Yes, replicate the root volumes option to +replicate the AFS cell's root volumes on this AFS Server. +
+

Choose the Next button. The System Control Service +dialog box appears. +
In cells running the domestic version of AFS for Windows, the System +Control Server distributes new versions of AFS Server configuration +information to all AFS servers and the System Control Client machines obtain +common AFS configuration files from the System Control machine. (Cells +running the international version of AFS for Windows do not use the System +Control Server to distribute system configuration files or the System Control +Client to obtain these files.) +
To configure this AFS Server as the System Control Server for the AFS +cell, choose the Configure as the System Control Server +option. To configure this AFS Server as a System Control Client, choose +the Configure as a System Control Client option and enter the +hostname of the System Control Server in this AFS cell. The AFS Server +will obtain new versions of AFS Server configuration information from the +server specified. If you do not want to configure this AFS Server as +the System Control Server for the AFS cell or as a System Control Client, +choose the Do not configure as the System Control Client or Server +option. +
Choose the Next button. The Configure the System dialog +box appears. +
A list of the steps that will be taken to configure this AFS Server is +displayed, enabling you to review the steps before starting the actual +configuration process. +
Note: To return to a previous step to review or modify your selections, choose the +Back button. +
+
To begin configuration of the AFS Server on this machine, choose the +Configure button. If you are configuring the AFS Server into +an AFS cell in which there are Database Servers running a version of AFS older +than version 3.5, a dialog box appears prompting you to enter the AFS +principal password. +
The AFS Server is configured according to your specifications. The +progress bar at the bottom of the dialog box indicates the steps in +progress. A message box appears indicating that configuration is +complete. +

To Configure the AFS Control Center

+ + +

Note:

If you have installed the AFS Control Center in combination with the AFS +Server, or the AFS Client, or both, then you do not need to configure the AFS +Control Center. The AFS Control Center is automatically configured when +the AFS Server or AFS Client is configured. If you have installed the +AFS Control Center only, then the Control Center must be configured on your +system before it can be used. +

From the Start menu, choose Settings, then choose +Control Panel. +
Double-click the AFS Control Center icon. The AFS +Control Center Properties dialog box appears. +
In the Default Cell box, enter the full name of the AFS cell to +be administered by default. +
If the cell to be administered by the AFS Control Center is not listed in +the list of AFS cells, choose the Add button. The New Cell +dialog box opens. Enter the cell name in the AFS Cell box +and a short description in the Description box. +
Choose the Add button. The Add Server dialog box +opens. In the Server Name box, enter the name of a Volume +Location Server in the selected cell. Choose OK to close the +Add Server dialog box. Repeat this process, adding information for all +Volume Location Servers in the cell. After all server information has +been entered, choose OK to close the New Cell dialog box. +
Choose OK to close the AFS Control Center Properties dialog +box. +

The AFS Control Center is now configured. + +

Uninstalling AFS for Windows

This section outlines uninstallation prerequisites, provides +instructions for uninstalling AFS for Windows, and lists the changes that the +uninstallation process makes to your system. + + +

Reinstalling and Upgrading

On a Windows NT machine, it is not necessary to uninstall +the components of AFS for Windows for the purpose of reinstalling or upgrading +the software. To reinstall or upgrade AFS for Windows, follow the +installation procedure described in To Install AFS for Windows. During the installation process, the +previously-installed AFS components are replaced. AFS configuration +information is preserved. +

On a Windows 95 or Windows 98 machine, you must uninstall the +previously-installed AFS Light component, as described in To Uninstall AFS for Windows, before reinstalling or upgrading AFS Light. + + + +

Uninstallation Prerequisites

Uninstalling AFS results in the deletion of all AFS application +files. These files cannot be deleted if other applications are using +them. For this reason, you must close all AFS dialog boxes before +uninstalling AFS for Windows. +

If you are uninstalling the AFS Server for the purpose of decommissioning +the machine, the following prerequisites are necessary to avoid loss of +data: +

If the AFS Server is functioning as a File Server, move all read/write +volumes to another AFS File Server, and remove all read-only volumes. +
Unconfigure the AFS Server. Open the AFS Server Configuration +utility and choose the Server tab. Clear all check boxes and +choose OK. +

+ + + + + + + +

To Uninstall AFS for Windows

From the Start menu, choose Settings, then choose +Control Panel. +
Double-click the Add/Remove Programs icon. The +Add/Remove Programs Properties dialog box appears, displaying the +Install/Uninstall tab. +
Close the Control Panel. +
Select the AFS component to be uninstalled, and select the +Add/Remove button. The Confirm File Deletion dialog box +appears, verifying that you want to remove the selected AFS for Windows +component. Click Yes to continue with the uninstallation +procedure. +
An AFS message box appears asking if you want to preserve configuration +information. Select Yes to preserve configuration +information or No to delete all configuration information. +(No configuration information is associated with the AFS Supplemental +Documentation component. If you are removing this component from your +system, the AFS message box does not appear.) +

The Remove Programs from your Computer dialog box opens, displaying the +components being removed from your system. +

Note:

A message box can possibly appear asking if you want to remove shared AFS +files that are no longer needed by other components. Click Yes To +All to completely remove the selected AFS component. +

The selected AFS for Windows component is now uninstalled. If you +installed a combination of AFS for Windows components, you must repeat Steps +4-6 to remove each component separately. +

Changes Made to Your System

+ +

Changes made to your system by uninstalling the AFS Client

Uninstalling the AFS Client makes the following changes to your +system: +

Removes all AFS Client files from the \Program +Files\Ibm\Afs\Client\Program directory, removes the Client +directory, and, if no other AFS components remain installed, removes the +Ibm directory. +
Note: The directories are not removed if they contain any files other +than those installed by the AFS for Windows setup program. +
+
Removes the IBM AFS program group from the Start +menu if no other AFS components remain installed. +
Removes the AFS Client Configuration icon from the Control +Panel. +
Removes the AFS Menu from the Windows NT Explorer's context +menu. +
Deletes the IBM AFS Client service. +
Removes AFS Client related registry entries from your system. Note +that if you chose to preserve configuration information, some information +remains in the registry after the uninstallation process. +

Changes made to your system by uninstalling AFS Light

Uninstalling AFS Light makes the following changes to your +system: +

Removes all AFS files from the \Program +Files\Ibm\Afs\Client\Program directory and removes the Ibm +directory. +
Note: The directories are not removed if they contain any files other +than those installed by the AFS for Windows setup program. +
+
Removes the IBM AFS program group from the Start +menu. +
Removes the AFS Light Configuration icon from the Control +Panel. +
Removes the AFS Menu from the Windows Explorer's context menu. +
Removes AFS Light related registry entries from your system. Note +that if you chose to preserve configuration information, some information +remains in the registry after the uninstallation process. +

Changes made to your system by uninstalling the AFS Server

Uninstalling the AFS Server makes the following changes to your +system: +

Removes all AFS Server files from the \Program +Files\Ibm\Afs\Server directory, removes the Server directory, +and, if no other AFS components remain installed, removes the Ibm +directory. +

Note:

These directories are not removed if they contain any files other +than those installed by the AFS for Windows setup program. +Also, if you chose to preserve configuration information, some files in the +\Program Files\Ibm\Afs\Server directory are not +removed. +

Removes the IBM AFS program group from the Start +menu if no other AFS components remain installed. +
Removes the AFS Server Configuration icon from the Control +Panel. +
Deletes the IBM AFS Server service. +
Removes AFS Server related registry entries from your system. Note +that if you chose to preserve configuration information, some information +remains in the registry after the uninstallation process. +

Changes made to your system by uninstalling the AFS Control Center

Uninstalling the AFS Control Center makes the following changes to your +system: +

Removes all AFS Control Center files from the \Program +Files\Ibm\Afs\Control Center directory, removes the Control +Center directory, and, if no other AFS components remain installed, +removes the Ibm directory. +
Note: These directories are not removed if they contain any files other +than those installed by the AFS for Windows setup program. +
+
Removes the IBM AFS program group from the Start +menu if no other AFS components remain installed. +
Removes the AFS Control Center icon from the Control +Panel. Note that this icon appears in the Control Panel only if no +other AFS for Windows components are installed on your system. +
Removes AFS Control Center related registry entries from your +system. Note that if you chose to preserve configuration information, +some information remains in the registry after the uninstallation +process. +

Changes made to your system by uninstalling the AFS supplemental documentation

Uninstalling the AFS supplemental documentation makes the following +changes to your system: +

Removes the SysAdminGd directory and the CmdRef +directory from the \Program Files\Ibm\Afs\Documentation\Html +directory, and, if no other AFS components remain installed, removes the +Ibm directory. +
Note: These directories are not removed if they contain any files other +than those installed by the AFS for Windows setup program. +
+
Removes the IBM AFS program group from the Start +menu if no other AFS components remain installed. +
Removes AFS supplemental documentation related registry entries from your +system. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/QuickStartWindows/awqbg004.htm b/doc/html/QuickStartWindows/awqbg004.htm new file mode 100755 index 0000000..507c334 --- /dev/null +++ b/doc/html/QuickStartWindows/awqbg004.htm @@ -0,0 +1,341 @@ + + +Quick Beginnings + + + + + + + + + + + +

Quick Beginnings

Index

+A +B +C +D +F +G +I +L +M +O +R +S +U +

+A + +

AFS + +

client + +

overview +(1) +

components +(1) +

configuration + +

AFS Client +(1) +

AFS Control Center +(1) +

AFS Light +(1) +

AFS Light Gateway +(1) +

AFS Server +(1) +

overview +(1) +

control center + +

overview +(1) +

installation options +(1) +

installation procedure +(1) +

light + +

overview +(1) +

reinstalling +(1) +

server + +

overview +(1) +

supplemental documentation component +(1) +

uninstallation prerequisites +(1) +

uninstallation procedure +(1) +

upgrading +(1) +

AFS Client +(1) + +

setup.co file +

client-only installation +(1) +

configuration +(1) +

configure as AFS Light Gateway +(1) +

installation +(1) +

overview +(1) +

uninstallation +(1) +

AFS Control Center + +

configuration +(1) +

installation +(1) +

overview +(1) +

uninstallation +(1) +

AFS Light + +

configuration +(1) +

gateway machine +(1) +

installation +(1) +

overview +(1) +

uninstallation +(1) +

AFS Light Gateway + +

authenticating AFS Light users +(1) +

configuration +(1) +

synchronizing the cell database +(1) +

AFS partitions +(1) +

AFS Server + +

configuration + +

as first server in a cell +(1) +

as server in an existing cell +(1) +

overview +(1) +

installation +(1) +

overview +(1) +

uninstallation +(1) +

audience +(1) +

+B + +

Backup Server + +

configuring in a new cell +(1) +

configuring in an existing cell +(1) +

+C + +

CD-ROM documentation +(1) +

client + +

overview +(1) +

client-only installation +(1) +

configuration +(1) +

control center + +

overview +(1) +

+D + +

Database Server + +

configuring in a new cell +(1) +

configuring in an existing cell +(1) +

documentation + +

CD-ROM +(1) +

online +(1) +

online help +(1) +

domain user accounts +(1) +

+F + +

File Server + +

configuring in a new cell +(1) +

configuring in an existing cell +(1) +

+G + +

gateway machine name +(1) +

generic administrative account +(1) +

+I + +

installation + +

changes made to your system +(1) +

client-only installation +(1) +

possible component combinations +(1) +

procedure +(1) +

upgrading from an earlier version +(1) +

installation options +(1) +

installation procedure +(1) +

+L + +

light + +

overview +(1) +

+M + +

machine user accounts +(1) +

+O + +

online documentation +(1) +

online help +(1) +

overview + +

AFS +(1) +

document +(1) +

+R + +

reinstalling +(1) +

replication + +

when configuring a new cell +(1) +

root AFS volumes + +

when configuring a new cell +(1) +

when configuring a server in an existing cell +(1) +

root.afs +(1) +

root.cell +(1) +

+S + +

server + +

overview +(1) +

setup.co file +(1) +

System Control Server + +

in a new AFS cell +(1) +

+U + +

uninstallation + +

changes made to your system +(1) +

overview +(1) +

prerequisites +(1) +

procedure +(1) +

uninstallation prerequisites +(1) +

uninstallation procedure +(1) +

upgrading +(1) +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/ReleaseNotes-3.6/aurns000.htm b/doc/html/ReleaseNotes-3.6/aurns000.htm new file mode 100644 index 0000000..200c88a --- /dev/null +++ b/doc/html/ReleaseNotes-3.6/aurns000.htm @@ -0,0 +1,49 @@ + + +Release Notes + + + + + + + + + + + +

Release Notes

+AFS
+Release Notes
+

Version 3.6 +

Document Number GC09-4558-00 +

0000000 +

+
+

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 +

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. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/ReleaseNotes-3.6/aurns002.htm b/doc/html/ReleaseNotes-3.6/aurns002.htm new file mode 100644 index 0000000..2453df0 --- /dev/null +++ b/doc/html/ReleaseNotes-3.6/aurns002.htm @@ -0,0 +1,88 @@ + + +Release Notes + + + + + + + + + + + +

Release Notes

About These Release Notes
+

Organization of the Document +

Summary of New Features +

AFS 3.6 Release Notes
+

Supported System Types +

Hardware and Software Requirements +

Accessing the AFS Binary Distribution and Documentation +

Product Notes + +

Product Notes for All System Types +

Product Notes for AIX Systems +

Product Notes for Digital UNIX Systems +

Product Notes for HP-UX Systems +

Product Notes for IRIX Systems +

Product Notes for Linux Systems +

Product Notes for Solaris Systems +

Documentation Notes +

Changes to AFS Commands, Files, and Functionality + +

A New Command +

New File or Command Functionality +

Support for Backup to TSM + +

New Command and File Features that Support TSM +

Product Notes for Use of TSM +

Configuring the Backup System and TSM +

Upgrading Server and Client Machines to AFS 3.6 + +

Prerequisites for Upgrading +

Obtaining the Binary Distribution +

Storing Binaries in AFS +

Upgrading the Operating System +

Distributing Binaries to Server Machines +

Upgrading Server Machines +

Upgrading Client Machines +

Incorporating AFS into the Kernel and Enabling the AFS Initialization Script +

Loading AFS into the AIX Kernel +

Building AFS into the Digital UNIX Kernel +

Building AFS into the HP-UX Kernel +

Incorporating AFS into the IRIX Kernel +

Loading AFS into the Linux Kernel +

Loading AFS into the Solaris Kernel +

Storing AFS Documents in AFS +

Reference Pages + +

CFG_tcid +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/ReleaseNotes-3.6/aurns003.htm b/doc/html/ReleaseNotes-3.6/aurns003.htm new file mode 100644 index 0000000..8b37a61 --- /dev/null +++ b/doc/html/ReleaseNotes-3.6/aurns003.htm @@ -0,0 +1,125 @@ + + +Release Notes + + + + + + + + + + + +

Release Notes

About These Release Notes

This section describes the purpose, organization, and conventions used in +this document. +

Audience and Purpose

This document describes new features, limitations and +requirements of the AFS^{^(R)} 3.6 General Availability (GA) +release. It assumes that the reader is familiar with administration of +AFS 3.5 and of the supported operating systems. +

Organization of the Document

This document has the following sections: +

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. +

For further information on the syntax and input rules for AFS commands, see +the appendix to the IBM AFS Administration Guide or the +afs_intro reference page in the IBM AFS Administration +Reference. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/ReleaseNotes-3.6/aurns004.htm b/doc/html/ReleaseNotes-3.6/aurns004.htm new file mode 100644 index 0000000..c434bea --- /dev/null +++ b/doc/html/ReleaseNotes-3.6/aurns004.htm @@ -0,0 +1,4262 @@ + + +Release Notes + + + + + + + + + + + +

Release Notes

AFS 3.6 Release Notes

This file documents new features, upgrade procedures, and remaining +limitations associated with the initial General Availability (GA) release of +AFS^{^(R)} 3.6 (build level afs3.6 +2.0). +
Note: This document includes all product information available at the time the +document was produced. For additional information that became available +later, see the README.txt file included on the AFS +CD-ROM. +
+

Summary of New Features

AFS 3.6 includes the following new features. +

Support for the 64-bit version of Solaris 7. +
Support for the 64-bit version of HP-UX 11.0. +
The HP-UX 11.0 File Server uses the POSIX-compliant threading +package provided with HP-UX. (Other supported operating systems started +using native threads in AFS 3.5.) See Product Notes for HP-UX Systems. +
There is a single edition of AFS 3.6, instead of separate United +States and international editions as in previous releases. The United +States government now permits export outside North America of the encryption +software that the Update Server uses to protect user-level data. With +AFS 3.6, cells outside North America can run a system control machine +to distribute the contents of the /usr/afs/etc directory among +server machines. +
The AFS 3.6 distribution includes a single CD-ROM for each system +type, which contains all AFS software. There is no CD-ROM labeled +Encryption Files or Domestic Edition in the AFS +3.6 distribution. +
Because they were produced before the change in export restrictions, the +IBM AFS Administration Guide and IBM AFS Administration +Reference still distinguish between United States and international +editions of AFS. However, AFS customers in any country can ignore the +distinction and use the United States instructions if they choose. +
Support for volumes up to 8 GB in size. In previous versions of +AFS, the limit was 2 GB. +
Note that smaller volumes are still more practical than large ones in +general. The larger a volume, the longer it takes to move or clone it, +which introduces greater potential for an outage to halt the operation before +it completes. +
Support for backing up AFS data to the Tivoli Storage Manager (TSM), +formerly called the ADSTAR Distributed Storage Manager (ADSM). TSM +implements the Open Group's Backup Service application programming +interface (API), also called XBSA. Support for additional +XBSA-compliant programs in future releases of AFS is possible. See Support for Backup to TSM. +
A new command and new options to existing commands. See Changes to AFS Commands, Files, and Functionality. +

Supported System Types

AFS supports the following system types. +
+ + + + + + + + +
alpha_dux40 + DEC AXP system with one or more processors running Digital UNIX +4.0d, 4.0e, or 4.0f +
hp_ux110 + Hewlett-Packard system with one or more processors running the 32-bit or +64-bit version of HP-UX 11.0 +
i386_linux22 + IBM-compatible PC with one or more processors running Linux kernel +version 2.2.5-15 (the version in Red Hat Linux 6.0), +2.2.10, 2.2.12, 2.2.12-20 (the +version in Red Hat Linux 6.1), 2.2.13, or +2.2.14 +
rs_aix42 + IBM RS/6000 with one or more 32-bit or 64-bit processors running AIX +4.2, 4.2.1, 4.3, 4.3.1, +4.3.2, or 4.3.3 +
sgi_65 + Silicon Graphics system with one or more processors running IRIX +6.5 or 6.5.4. Support is provided for the +following CPU board types, as reported by the IRIX uname -m +command: IP19, IP20, IP21, IP22, IP25, IP26, IP27, IP28, IP30, IP32 +
sun4x_56 + Sun SPARCstation with one or more processors running Solaris 2.6 +
sun4x_57 + Sun SPARCstation with one or more processors running the 32-bit or 64-bit +version of Solaris 7 +
+

Hardware and Software Requirements

For a list of requirements for both server and client +machines, see the chapter titled Installation Overview in the +IBM AFS Quick Beginnings document. +

Accessing the AFS Binary Distribution and Documentation

The AFS Binary Distribution includes a separate CD-ROM for +each supported operating system, containing all AFS binaries and files for +both server and client machines, plus the documentation set in multiple +formats. At the top level of the CD-ROM is a directory called +Documentation plus a directory containing the system-specific AFS +binaries, named using the values listed in Supported System Types. The CD-ROM for some operating systems has more than +one system-specific directory; for example, the Solaris CD-ROM has +sun4x_56 and sun4x_57. +

The instructions in Upgrading Server and Client Machines to AFS 3.6 specify when to mount the CD-ROM and which files or +directories to copy to the local disk or into an AFS volume. +

The documents are also available online at <A +HREF="http://www.transarc.com/Library/documentation/afs_doc.html">http://www.transarc.com/Library/documentation/afs_doc.html</A>. +The documentation set includes the following documents: +

IBM AFS Release Notes (this document) +
IBM AFS Administration Guide (called AFS System +Administrator's Guide in previous releases) +
IBM AFS Administration Reference (called AFS Command +Reference Manual in previous releases) +
IBM AFS Quick Beginnings (called AFS Installation +Guide in previous releases) +
IBM AFS User Guide (called AFS User's Guide in +previous releases) +

Documents are provided in the following formats: +

HTML, suitable for online viewing in a Web browser or other HTML viewer +
PDF, suitable for online viewing or for printing using the Acrobat Reader +program from Adobe +

If you do not already have the Acrobat Reader program, you can download it +for free at <A +HREF="http://www.adobe.com/products/acrobat/readstep.html">http://www.adobe.com/products/acrobat/readstep.html</A>. +

Adobe provides only an English-language version of Acrobat Reader for UNIX +platforms. The program can display PDF files written in any +language. It is the program interface (menus, messages, and so on) that +is available in English only. +

To make Reader's interface display properly in non-English language +locales, use one of two methods to set the program's language environment +to English: +

Set the LANG environment variable in the Reader initialization +script. The advantage of this method is that it ensures proper behavior +even when Reader is launched by other applications, such as a browser or an +application's Help menu. Editing the script usually requires local +superuser root privilege, however. +
If your Reader distribution includes the script, it is installed by +convention as AcroRead_Dir/bin/acroread, where +AcroRead_Dir is the installation directory for Reader files. +
Add the following line to the script, directly after the +#!/bin/sh statement: +
```
   LANG=C; export LANG
+
```
+
Set the LANG environment variable to the value C in the command +shell before starting the Reader program. The following is the +appropriate command for some shells. +
```
   % setenv LANG C
+
```
+
Note that this setting affects all programs started in the command shell, +with possibly undesirable results if they also use the LANG variable. +The preceding method affects Reader only. +

Product Notes

The following sections summarize limitations and +requirements that pertain to all system types and to individual system types, +and describe revisions to the AFS documents: +

Product Notes for All System Types +
Product Notes for AIX Systems +
Product Notes for Digital UNIX Systems +
Product Notes for HP-UX Systems +
Product Notes for IRIX Systems +
Product Notes for Linux Systems +
Product Notes for Solaris Systems +
Documentation Notes +

Product Notes for All System Types

Limit on number of file server machine interfaces +
AFS supports up to 15 addresses on a multihomed file server machine. +If more interfaces are configured with the operating system, AFS uses only the +first 15. +
Limit on number of client machine interfaces +
AFS supports up to 32 addresses on a multihomed client machine. Do +not configure more interfaces. +
Limit on number of AFS server partitions +
AFS supports up to 256 server (/vicep) partitions on a file +server machine. This corresponds to directory names /vicepa +through /vicepz and /vicepaa through +/vicepiv. +
Limit on number of file server machines +
The VLDB can store up to 255 server entries, each representing one file +server machine (single- or multihomed). This effectively determines the +maximum number of file server machines in the cell. To make room in the +VLDB for new server entries, use the vos changeaddr command's +-remove argument to remove the entries for decommissioned file +server machines. +
Limit on file size +
AFS supports a maximum file size of 2 GB. +
Limit on volume and partition size +
AFS supports a maximum volume size of 8 GB. In AFS version +3.5 and earlier, the limit is 2 GB. There is no limit on +partition size other than the one imposed by the operating system. +
Limit on cache size +
AFS supports a maximum disk cache size of 1 GB. In AFS version +3.1 and earlier, the limit is 700 MB. +
Limit on number of File Server threads +
The File Server (fileserver process) can use up to 128 threads, +unless the operating system imposes a lower limit. Testing for the AFS +3.6 GA release indicates that HP-UX sometimes imposes a lower limit, +depending on the resources available on a machine. See Product Notes for HP-UX Systems. +
The File Server always reserves seven threads for special uses, so the +maximum effective value for the fileserver command's +-p argument is seven less than the actual limit. On most +systems, the effective maximum is therefore 121. +
Limit on number of volume site definitions +
The VLDB entry for a volume can accommodate a maximum of 13 site +definitions. The site housing the read/write and backup versions of the +volume counts as one site, and each read-only site counts as an additional +site (even the read-only site defined on the same partition as the read/write +site counts as a separate site). +
No support for VxFS as server or cache partition +
AFS does not support use of the VxFS file system as either a client cache +partition or server (/vicep) partition. It is acceptable to +use both VxFS and AFS on the same machine, but the cache partition and all AFS +server partitions must use a supported file system type such as UFS. +See the following sections of this document for similar restrictions affecting +particular operating systems. +
Run same version of a server process on all server machines +
For predictable performance, run the same version of an AFS server process +on all server machines in a cell. For example, if you upgrade the +Volume Location Server process on a database server machine to AFS 3.6, +you must upgrade it on all of them. The upgrade instructions in Upgrading Server and Client Machines to AFS 3.6 have you upgrade the binaries for all server processes on +all machines to the same version, and in general that is the best +policy. Unless otherwise noted, it is acceptable to run different build +levels of a major version on different machines (for example, AFS 3.5 +build 3.0 on one machine and AFS 3.5 build 3.11 on +another). +
Single edition of AFS for all countries +
There is a single edition of AFS 3.6 for both North American and +international customers. For details, see Summary of New Features. +
TSM is the supported XBSA server +
The AFS 3.6 Backup System can communicate with one XBSA server, the +Tivoli Storage Manager (TSM). There are several requirements and +limitations associated with its use, as detailed in Product Notes for Use of TSM. +
Use Netscape 4.0 or higher +
If using a Netscape browser to read the HTML version of an AFS document, +use version 4.0 or higher. Some fonts used in the documents +possibly do not display properly in earlier versions. +
Set the Acrobat Reader environment to English +
The user interface to the Adobe Acrobat Reader program for displaying PDF +files works correctly only when the program's language environment is set +to English. Users in non-English language locales probably need to +adjust the language setting. See Accessing the AFS Binary Distribution and Documentation. +
No support for IPv6 +
AFS does not support version 6 of the Internet Protocol (IPv6). You +must continue to specify the IPv4 protocol names udp and +tcp in the entries for AFS-modified services in the +inetd configuration file, rather than the IPv6 names +upd6 and tcp6. If you use the IPv6 version, the +AFS-modified inetd daemon cannot locate the service and does not +open the service's port. +
The inetd configuration file included with some operating system +revisions possibly specifies IPv6 protocols by default. You must modify +or replace the file in order to use the AFS-modified version of remote +services. +
Limit on directory size when element names are long +
If the name of every file system element (file, link, or subdirectory) in a +directory is 16 characters or more, then when there are about 31,700 elements +it becomes impossible to create any more elements with long names. It +is still possible to create elements with names shorter than 16 +characters. This limitation is due to the way AFS implements +directories. For a more detailed explanation, contact your AFS product +support representative. +
Setting setuid or setgid bit on file fails silently +
Only members of the system:administrators group can turn +on the setuid or setgid mode bit on an AFS file or directory. However, +AFS generates an error message only when a regular user attempts to set the +bit on a directory. Attempts on a file fail silently. +
The add instruction in the uss bulk input file does not work as +documented +
The documentation specifies the following syntax for creating an +authentication-only account (entries in the Authentication and Protection +Databases only) by using an add instruction in the uss +bulk template file: +
```
   add username[:]
+
```
+
However, you must in fact follow the username value with two +colons for the uss bulk command to create the account: +
```
   add username::
+
```
+
Running the backup savedb command blocks other Backup System +operations +
The Backup Server locks the Backup Database as it performs the backup +savedb command, which can take a long time. Because other backup +operations cannot access the database during this time, they appear to +hang. Avoid running other backup operations after issuing the +backup savedb command. +
Actually, this limitation applies to any operation that locks the Backup +Database for a significant amount of time, but most other operations do +not. In any case, running the backup savedb command is +appropriate only in the rare case when the Backup Database is corrupted, so +this limitation usually does not have a significant impact. +
NFS/AFS Translator sometimes performs poorly under heavy load +
The NFS/AFS Translator does not always perform well under heavy +load. Sometimes the translator machine hangs, and sometimes NFS client +machines display the following error message. +
```
   NFS Stale File Handle   
+
```
+
Sample files for package program not included +
The AFS distribution does not include the sample files referred to in the +chapter of the IBM AFS Administration Guide about the +package program (the files formerly installed by convention in the +etc, lib, and src subdirectories of the +/afs/cellname/wsadmin directory). +IBM AFS Quick Beginnings therefore does not include instructions +for installing the sample files. If you wish to use the +package program and the discussion in the IBM AFS +Administration Guide is not sufficient to guide you, contact your AFS +product support representative for assistance. +

Product Notes for AIX Systems

The klog command's -setpag flag is supported on AIX +4.2.1 and 4.3.3 only +
To use the klog command's -setpag flag, you must +install the indicated AIX APAR (Authorized Program Analysis Report), available +from IBM, on a machine running the indicated AIX version: +
- APAR IY07834 on AIX 4.2.1 machines +
- APAR IY07835 on AIX 4.3.3 machines +
+
To determine if the APAR is installed, issue the following command: +
```
   % instfix -i -k APAR_identifier
+
```
+
IBM provides an APAR for the indicated (latest) AIX versions only. +Therefore, the -setpag flag does not work correctly on machines +running the base level of AIX 4.2 or 4.3, or AIX +4.3.1 or 4.3.2. +
Change to AFS installation procedure for AIX +4.3.3 +
If version 4.3.3.0 or higher of the AIX +bos.rte.security fileset is installed (usually true +on a machine using the AIX 4.3.3 kernel), you must modify the +procedure documented in IBM AFS Quick Beginnings for enabling +integrated AFS login. Instead of editing the +/etc/security/login.cfg file, you edit the +/usr/lib/security/methods.cfg file. +
To determine which version of the bos.rte.security +fileset is installed, issue the following command: +
```
   # lslpp -L bos.rte.security
+
```
+
The change affects Step 3 in the section titled Enabling AFS Login on +AIX Systems in each of two chapters in IBM AFS Quick +Beginnings: Installing the First AFS Machine and +Installing Additional Client Machines. For the complete text +of the modified step, see Documentation Notes. +
No support for the NFS/AFS Translator with base level of AIX +4.2 +
AFS does not support the use of machines running the base level of AIX +4.2 as NFS/AFS Translator machines. The AFS distribution does +not include the required kernel extensions file, formerly installed by +convention as +/usr/vice/etc/dkload/afs.ext.trans. Do not set +the NFS variable to the value $NFS_NFS in the AFS initialization +script (by convention, /etc/rc.afs). +
Machines running AIX 4.2.1 and higher are supported as +NFS/AFS Translator machines. They use the +afs.ext.iauth kernel extensions file instead. +
NFS/AFS Translator cannot coexist with NFS/DFS Gateway +
A machine running AIX 4.2.1 or higher cannot act as both an +NFS/AFS Translator and a NFS/DFS Gateway Server at the same time, because both +translation protocols must have exclusive access to the AIX iauth +interface. An attempt by either file system to access the +iauth interface when the other file system is already using it +fails with an error message. +
No support for NFS Version 3 software on NFS clients +
Do not run NFS Version 3 software on NFS client machines that use an +NFS/AFS Translator machine running AIX. The NFS3 client software uses +the readdir+ NFS command on directories, which can cause excessive +volume lookups on the translator machine. This can lead to timeouts, +especially when used in the /afs directory or other directories +with many volume mount points. Use NFS Version 2 instead. +
No support for Large File Enabled Journalled File System as AFS +server partition +
AFS does not support use of AIX's Large File Enabled Journalled File +System as an AFS server (/vicep) partition. If you configure +a partition that uses that file system as an AFS server partition, the File +Server ignores it and writes the following message to the +/usr/afs/logs/FileLog file: +
```
   /vicepxx is a big files filesystem, ignoring it
+
```
+
AFS supports use of the Large File Enabled Journalled File System as the +cache partition on a client machine. +
PASSWORD_EXPIRES variable not set on AIX +
The AIX secondary authentication system does not support setting the +PASSWORD_EXPIRES environment variable during login. +
The chuser, chfn and chsh commands are inoperative +
The chuser, chfn, and chsh commands are +inoperative on AFS machines running AIX. AFS authentication uses the +AIX secondary authentication system, and sets the registry variable +in the /etc/security/user file to DCE for the default +user. That is, the setting is +
```
   registry = DCE
+
```
+
as described in the sections of IBM AFS Quick Beginnings that +discuss enabling AFS login on AIX systems. However, when the +registry variable has any value other than registry = +files, AIX does not allow edits to /etc/passwd and related +files, and so disallows the chuser, chfn and +chsh commands. Attempts to edit entries by running these +commands on the command line result in error messages like the +following. +
- From the chuser command: +
```
   You can only change the HOME directory on the name server.   
+
```
  +
- From the chfn command: +
```
   You can only change the User INFORMATION on the name server.   
+
```
  +
- From the chsh command: +
```
   You can only change the Initial PROGRAM on the name server.   
+
```
  +
+
From within SMIT, using the chuser function results in an error +message like the following: +
+
```
    3004-716: You can only change the HOME directory on the name server
+
```
+
It is not possible for AFS Development to alter this behavior, because AIX +imposes the restriction. Sites that wish to run these commands must +develop a solution appropriate for their needs. +

Product Notes for Digital UNIX Systems

No support for the NFS/AFS Translator +
AFS does not support use of Digital UNIX machines as NFS/AFS Translator +machines. +
No support for AdvFS as server or cache partition +
AFS does not support use of Digital UNIX's Advanced File System +(AdvFS) as either a client cache partition or a server (/vicep) +partition. It is acceptable to use both AdvFS and AFS on the same +machine, but the cache partition and all AFS server partitions must be UFS +partitions. +
No support for real-time kernel preemption or related lock +modes +
AFS does not function correctly on a Digital UNIX machine when real-time +preemption of system calls is enabled in the kernel. Do not enable this +feature in any manner, including the following: +
- By including the following statement in the /usr/sys/conf/AFS +file: +
```
   options RT_PREEMPT_OPT   
+
```
  +
- By including either of the following instructions in the +/etc/sysconfigtab file: +
```
   rt_preempt_opt=1  
+   rt-preempt-opt=1
+
```
  +
+
Also, AFS does not function correctly when the value of the kernel +lockmode option is other than 0 (zero, the default) or +2. Lock mode values 1, 3, and +4 are unsupported because they imply that real-time preemption is +enabled (indeed, enabling real-time preemption sets the lock mode to +1 automatically). +
Building AFS from source requires /usr/sys/AFS directory +
Building AFS from source for Digital UNIX requires that certain header +files (such as cpus.h) reside in the local +/usr/sys/AFS directory. This directory exists only if you +have previously incorporated AFS modifications into the kernel of the machine +on which you are performing the compilation. Otherwise, the required +header files reside only in the local directory called +/usr/sys/machine_name. +
If the /usr/sys/AFS directory does not exist, issue the +following command to create it as a link: +
```
    # ln -s  /usr/sys/machine_name  /usr/sys/AFS
+
```
+
When the compilation is complete, remove the link. +

Product Notes for HP-UX Systems

No support for the NFS/AFS Translator +
AFS does not support use of HP-UX 11.0 machines as NFS/AFS +Translator machines. +
Upgrade kernel extensions when upgrading the File Server +
The AFS 3.6 version of the File Server uses the native HP-UX +threading package. When upgrading to the new File Server on a machine +that previously ran File Server version 3.5 or earlier, you must also +upgrade the AFS kernel extensions to the AFS 3.6 version. +
For instructions on upgrading server and client machines, see Upgrading Server and Client Machines to AFS 3.6. +
Possible lower limit on number of File Server threads +
On some machines, HP-UX reduces the number of threads available to the File +Server to fewer than the AFS default of 128. To determine the maximum +number of threads available to the File Server (or any single process) on an +HP-UX machine, issue the following command: +
```
   % getconf _SC_THREAD_THREADS_MAX
+
```
+
As on other system types, the HP-UX File Server reserves seven threads for +special uses, so the maximum effective value for the fileserver +command's -p argument is seven less than the number reported +by the getconf command. +
PAM can succeed inappropriately when pam_dial_auth module is +optional +
For AFS authentication to work correctly for a service, all entries for the +service in the HP-UX PAM configuration file (/etc/pam.conf +by convention) must have the value optional in the third field, as +specified in IBM AFS Quick Beginnings. However, when you +make the login entry that invokes the pam_dial_auth +module optional in this way, it can mean that PAM succeeds (the user can +login) even when the user does not meet all of the pam_dial_auth +module's requirements. This is not usually considered +desirable. +
If you do not use dial-up authentication, comment out or remove the entry +for the login service that invokes the pam_dial_auth +module. If you do use dial-up authentication, you must develop a +configuration that meets your needs; consult the HP-UX documentation for +PAM and the pam_dial_auth module. +
HP patch PHCO_18572 enables PAM to change to home directory +
You must install Hewlett-Packard patch PHCO_18572 to enable HP-UX's +standard PAM to change to a user's home directory during login. +The patch is accessible for download via the UNIX File Transfer Protocol +(ftp) at the following address: +
+
ftp://hpatlse.atl.hp.com/hp-ux_patches/s700_800/11.X/PHCO_18572 +
+
The patch is also available from HP Electronic Support Centers at the +following URLs. +
- In the Americas and Asia Pacific: <A +HREF="http://us-support.external.hp.com">http://us-support.external.hp.com</A> +
- In Europe: <A +HREF="http://europe-support.external.hp.com">http://europe-support.external.hp.com</A> +
+

Product Notes for IRIX Systems

kdump program does not work with dynamically loaded kernels +
The AFS kernel dump program, kdump, cannot retrieve kernel +information from an IRIX system on which the dynamic kernel loader, +ml, was used to load AFS extensions. The kdump +program can read only static kernels into which AFS is built. +
No AFS-modified remote commands +
The AFS distribution for IRIX machines does not include AFS-modified +versions of any of the remote (r*) commands except +inetd.afs. Silicon Graphics has already modified the +IRIX versions of the remote commands to be compatible with AFS. +
Do not run the fsr program +
Do not run the IRIX File System Reorganizer (fsr program) on a +client cache partition (/usr/vice/cache directory or equivalent) or +AFS server partition (/vicep directory). The program can +corrupt or remove AFS data. +
The timed daemon runs by default +
The IRIX 6.5 distribution includes and starts the timed +time-synchronization daemon by default. If you want to use the +runntp program and the Network Time Protocol Daemon (NTPD) on AFS +server machines, as documented in IBM AFS Quick Beginnings, issue +the following commands. They disable the timed daemon and +remove it from the machine's startup sequence. +
```
   # /etc/chkconfig -f timed off
+   
+   # /sbin/killall timed      
+
```
+
Default login program does not grant AFS tokens +
The IRIX 6.5 distribution includes the clogin program as +the default login utility. This graphical utility does not grant AFS +tokens. If you want your users to obtain tokens during login, you must +disable the clogin program and substitute either the standard +command-line login program or the xdm graphical login +utility, both of which grant AFS tokens if AFS modifications have been +incorporated into the kernel. Issue the following command to disable +the clogin program. +
```
   # /etc/chkconfig -f visuallogin off   
+
```
+

Product Notes for Linux Systems

Supported kernel versions +
The General Availability release of AFS 3.6 supports Red Hat +Software's Linux 6.0 (which incorporates kernel version +2.2.5-15) and Linux 6.1 (which incorporates kernel +version 2.2.12-20). The distribution also includes +AFS kernel extensions for kernel versions 2.2.10, +2.2.12, 2.2.13, and 2.2.14. +The AFS initialization script included in the AFS 3.6 distribution +automatically selects the appropriate kernel extensions for the kernel version +in use on the local machine. +
Red Hat Linux 6.0 and 6.1 include a compiled kernel, but for +the other supported kernel versions you must obtain kernel source and compile +the kernel yourself. In this case, you must use version +2.7.2.3 or higher of the gcc program, which is +part of the Linux distribution. Do not use other compilers. +
The Linux kernel-building tools by default create a symmetric +multiprocessor (SMP) kernel, which can run on both uniprocessor and +multiprocessor machines. However, a uniprocessor machine generally +performs best with a uniprocessor kernel. +
You can obtain Linux kernel source via the UNIX File Transfer Protocol +(ftp) at ftp.kernel.org or one of its +mirror sites. There is also kernel upgrade information at <A +HREF="http://www.kernel.org">http://www.kernel.org</A>. +
AFS requires libc6 +
For correct AFS performance, the operating system must use the C library +called libc6 (or glibc2), rather than libc5 +(glibc1). +
Modified insmod program required with some kernels +
If using an SMP kernel or a uniprocessor kernel configured to use more than +1 GB of memory, you must use a modified version of the insmod +program. You do not need the modified program if using a standard +uniprocessor kernel. +
You can download the modified insmod program at the following +URLs: +
- <A +HREF="http://www.transarc.com/Support/afs/index.html">http://www.transarc.com/Support/afs/index.html</A>. +See the Downloads section of the page. To comply with the +GNU Public License (GPL), the download site also makes available the complete +modified insmod.c source file and a source-code patch +against the original insmod.c file. +
- <A +HREF="http://www.pi.se/blox/modutils/index.html">http://www.pi.se/blox/modutils/index.html</A>. +Select the file listed at the top of the index. This is a site for +Linux modutils source code. +
+
No support for the NFS/AFS Translator +
AFS does not support the use of Linux machines as NFS/AFS Translator +machines. +
No AuthLog database +
The Authentication Server running on a Linux machine creates and writes +messages to the /usr/afs/logs/AuthLog file, just as on other system +types. However, it does not create or use the two files which +constitute the auxiliary AuthLog database on other system types +(AuthLog.dir and AuthLog.pag). The +kdb command is therefore inoperative on Linux machines. The +auxiliary database is useful mostly for debugging and is not required for +normal operations. +
Curses utility required for monitoring programs +
For the afsmonitor, scout and fms programs +to work properly, the dynamic library /usr/lib/libncurses.so +must be installed on the machine. It is available in most Linux +distributions. +

Product Notes for Solaris Systems

Different location for 64-bit Solaris 7 kernel extensions +
+
As noted in Upgrading Server and Client Machines to AFS 3.6, the 64-bit version of Solaris 7 uses a different +location for kernel extension library files than previous versions of +Solaris: /kernel/fs/sparcv9/afs. The 32-bit +version of Solaris 7 uses the same location as Solaris 2.6, +/kernel/fs/afs. +
SunSoft Patch 106541 for Solaris 7 replaces the /sbin/mountall +script +
As part of replacing the standard fsck program on an AFS file +server machine that runs Solaris, you make two changes in the +/sbin/mountall script. If you use Solaris 7 and apply +SunSoft Patch 10654, it replaces the /sbin/mountall script. +This has two implications: +
1. If you apply the patch on an existing file server machine, the changes you +already made in the /sbin/mountall script are overwritten. +You must make the changes again in the new (replacement) script. +
2. In the replacement script, the appearance of one of the sections of code +that you must alter is different than in the original script and as specified +in IBM AFS Quick Beginnings. +
+
For more details, see Documentation Notes. +
PAM can succeed inappropriately when pam_dial_auth module is +optional +
For AFS authentication to work correctly for a service, all entries for the +service in the Solaris PAM configuration file (/etc/pam.conf +by convention) must have the value optional in the third field, as +specified in IBM AFS Quick Beginnings. However, when you +make the login entry that invokes the pam_dial_auth +module optional in this way, it can mean that PAM succeeds (the user can +login) even when the user does not meet all of the pam_dial_auth +module's required conditions. This is not usually considered +desirable. +
If you do not use dial-up authentication, comment out or remove the entry +for the login service that invokes the pam_dial_auth +module. If you do use dial-up authentication, you must develop a +configuration that meets your needs; consult the Solaris documentation +for PAM and the pam_dial_auth module. +
The AFS Development group has filed a Request for Enhancement (RFE +#4122186) with SunSoft for a design change that eliminates this problem with +the pam_dial_auth module. There is no projected solution +date. For further information, contact your AFS product support +representative. +
Solaris 2.6 patches are required for CDE +
There were several defects in the initial release of the Solaris 2.6 +implementation of the Common Desktop Environment (CDE). They prevented +integrated AFS login from working consistently under CDE. SunSoft now +provides patches that correct the problems. You must install them in +order to obtain support for use of CDE from your AFS product support +representative. +
- If using version 1.2 of the Solaris CDE, install SunSoft patches +105703-03 and 106027-01 (or later revisions). +
- If using version 1.3 of the Solaris CDE, which is included on the +SDE CD-ROM, install SunSoft patch 106661-04 (or a later +revision). +
+
Use the following command to determine which version of CDE you are +running: +
```
   % pkginfo  -l  SUNWdtdte   
+
```
+

Documentation Notes

Instructions for international edition of AFS are obsolete +
As noted in Summary of New Features, the IBM AFS Administration Guide and IBM +AFS Administration Reference distinguish between United States and +international editions of AFS, because the documents were produced before a +relaxation of United States government export restrictions. AFS +3.6 includes just one edition. AFS customers in any country can +ignore the documented distinction between editions and use the United States +instructions if they choose. +
Clarification on obtaining technical support +
The AFS documents refer you to the AFS Product Support group for +technical assistance with AFS problems and questions. This is intended +to be a generic term. To learn how to obtain technical support, consult +your AFS license agreement or other materials from your AFS vendor. +
Change to IBM AFS Quick Beginnings instructions +for enabling AFS login on AIX machines +
If version 4.3.3.0 or higher of the AIX +bos.rte.security fileset is installed (usually true +on a machine using the AIX 4.3.3 kernel), edit the +/usr/lib/security/methods.cfg file instead of the +/etc/security/login.cfg file as documented in IBM AFS +Quick Beginnings. +
The change affects Step 3 in the section titled Enabling AFS Login on +AIX Systems in each of two chapters in IBM AFS Quick +Beginnings: Installing the First AFS Machine and +Installing Additional Client Machines. The corrected text +follows. +
+
Create or edit the DCE and AFS stanzas in one of two +files on the local disk: +
- The /usr/lib/security/methods.cfg file, if version +4.3.3.0 or higher of the AIX +bos.rte.security fileset is installed on the machine +(usually true on a machine using the AIX 4.3.3 kernel) +
- The /etc/security/login.cfg file, if an earlier version +of the fileset is installed +
+
Edit the stanzas as follows: +
- In the DCE stanza, set the program attribute as +indicated. +
  If you use the AFS Authentication Server (kaserver +process): +
```
   DCE:
+        program = /usr/vice/etc/afs_dynamic_auth   
+
```
  +
  If you use a Kerberos implementation of AFS authentication: +
```
   DCE:
+        program = /usr/vice/etc/afs_dynamic_kerbauth   
+
```
  +
- In the AFS stanza, set the program attribute as +indicated. +
  If you use the AFS Authentication Server (kaserver +process): +
```
   AFS:
+        program = /usr/vice/etc/afs_dynamic_auth   
+
```
  +
  If you use a Kerberos implementation of AFS authentication: +
```
   AFS:
+        program = /usr/vice/etc/afs_dynamic_kerbauth   
+
```
  +
+
Change to IBM AFS Quick Beginnings instructions +for replacing Solaris fsck program +
In two sections of IBM AFS Quick Beginnings, there are +instructions for editing the /sbin/mountall script on Solaris +machines as part of replacing the standard fsck program. The +two sections are Configuring the AFS-modified fsck Program on Solaris +Systems in the chapter about the first AFS machine and Getting +Started on Solaris Systems in the chapter about additional server +machines. +
If you use Solaris 7 and apply SunSoft Patch 10654, it replaces the +/sbin/mountall script. In the replacement script, the +appearance of one of the sections of code that you must alter is different +than in the original script and as specified in IBM AFS Quick +Beginnings, which is as follows: +
```
   # For fsck purposes, we make a distinction between ufs and
+   # other file systems
+   #
+   if [ "$fstype" = "ufs" ]; then
+        ufs_fscklist="$ufs_fscklist $fsckdev"
+        saveentry $fstype "$OPTIONS" $special $mountp
+        continue
+   fi  
+
```
+
In the replacement script, the code is instead similar to the +following: +
```
   # For fsck purposes, we make a distinction between ufs and
+   # other file systems.  Here we check that the file system is
+   # not mounted using fsck -m before adding it to the list to
+   # be checked
+   #
+   if [ "$fstype" = "ufs" ]; then
+        /usr/sbin/fsck -m -F $fstype $fsckdev >/dev/null 2>&1
+        if [ $? != 33 ]; then
+                ufs_fscklist="$ufs_fscklist $fsckdev"
+                saveentry $fstype "$OPTIONS" $special $mountp
+                continue
+        else
+                echo "$fsckdev already mounted"
+                continue
+        fi  
+   fi
+   
+
```
+
You still need to change the first if statement (the one +directly after the comment) to check for both the UFS and AFS file system +types, as specified in IBM AFS Quick Beginnings: +
```
   if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then   
+
```
+
Correction to IBM AFS Quick Beginnings +instructions for accessing AFS documents +
The section of IBM AFS Quick Beginnings titled Storing AFS +Documents in AFS (in the chapter about the first AFS machine) +incorrectly describes the organization of the top-level +Documentation directory on the AFS CD-ROM. It states that +there is a subdirectory for each document format. Instead, there is a +subdirectory for each language in which the documents are available, named +using the following codes: +
+
de_DE for German +
en_US for United States English +
es_ES for Spanish +
ko_KR for Korean +
pt_BR for Brazilian Portuguese +
zh_CN for Simplified Chinese +
zh_TW for Traditional Chinese +
+
In each language directory is a subdirectory for each available document +format. In each format directory is a subdirectory for each +document. For example, the path on the CD-ROM to the English-language +HTML version of the IBM AFS Quick Beginnings is +Documentation/en_US/HTML/QkBegin. +
Note: Not all documents are available in every language, as determined by the IBM +translation center responsible for each language. All documents are +available in English. +
+
Assuming that you want to install the documentation for one language only, +substitute the following text for Step 5 in the instructions in Storing +AFS Documents in AFS: +
+
Copy the AFS documents in one or more formats from the CD-ROM into +subdirectories of the /afs/cellname/afsdoc +directory. Repeat the commands for each format. +
```
   # mkdir format_name
+  
+   # cd format_name
+  
+   # cp -rp /cdrom/Documentation/language_code/format  .      
+
```
+
If you choose to store the HTML version of the documents in AFS, note that +in addition to a subdirectory for each document there are several files with a +.gif extension, which enable readers to move easily between +sections of a document. The file called index.htm is +an introductory HTML page that contains a hyperlink to each of the +documents. For online viewing to work properly, these files must remain +in the top-level HTML directory (the one named, for example, +/afs/cellname/afsdoc/HTML). +
Revised reference page for NetRestrict files +
The IBM AFS Administration Guide and IBM AFS Administration +Reference incorrectly state that the value 255 acts as a +wildcard in IP addresses that appear in the NetRestrict file +(client or server version). Wildcarding does not work and is not +supported. For corrected documentation, see NetRestrict (client version) and NetRestrict (server version). +
Revised reference pages for backup commands and configuration +file +
The IBM AFS Administration Guide and IBM AFS Administration +Reference do not document the interoperation of the AFS Backup System +and the Tivoli Storage Manager (TSM), because support for TSM was added after +the documents were produced. +
For a complete description of the new TSM-related features and +configuration procedures, see Support for Backup to TSM and the indicated reference pages: +
+
backup deletedump +
backup dumpinfo +
backup status +
CFG_tcid +
+
Revised reference page for vos delentry command +
The IBM AFS Administration Guide and IBM AFS Administration +Reference incorrectly state that the vos delentry command +accepts the name or volume ID number of any type of volume (read/write, +read-only, or backup). In fact, it accepts only a read/write +volume's name or ID. Because a single VLDB entry represents all +versions of a volume (read/write, readonly, and backup), the command removes +the entire entry even though only the read/write volume is specified. +For complete documentation, see vos delentry. +

Changes to AFS Commands, Files, and Functionality

This section briefly describes commands, command +options, and functionality that are new or changed in AFS 3.6. +Unless otherwise noted, the IBM AFS Administration Guide and +IBM AFS Administration Reference include complete documentation of +these items. +

A New Command

AFS 3.6 includes the new fs flushmount +command. The command's intended use is to discard information +about mount points that has become corrupted in the cache. The next +time an application accesses the mount point, the Cache Manager must fetch the +most current version of it from a File Server. Data cached from files +or directories in the volume is not affected. The only other way to +discard the information is to reinitialize the Cache Manager by rebooting the +machine. +

Symptoms of a corrupted mount point included garbled output from the +fs lsmount command, and failed attempts to change directory to or +list the contents of the volume root directory represented by the mount +point. +

New File or Command Functionality

AFS 3.6 adds the following new options and +functionality to existing commands and files. +

Changes that support XBSA servers +
Several backup commands and configuration files include new +features that support backup to XBSA servers such as TSM. See New Command and File Features that Support TSM. +
New instructions in the CFG_tcid file +
There are new instructions in the CFG_tcid file that +apply to all types of backup media: CENTRALLOG, +GROUPID, LASTLOG, MAXPASS, and +STATUS. (There are also new instructions that apply only to +XBSA servers, as documented in New Command and File Features that Support TSM.) +
The new instructions are not documented in the IBM AFS Administration +Guide or IBM AFS Administration Reference. See CFG_tcid. (Note that this is a new way of referring to this +file, called CFG_device_name in the IBM AFS +Administration Guide and IBM AFS Administration +Reference. For a Tape Coordinator that communicates with an XBSA +server, the variable part of the filename is a port offset number rather than +a device name, so the more generic tcid is a better description of +possible values in this part of the filename.) +
New -temporary flag to backup addvolset command +
The backup addvolset command has a new -temporary +flag. A temporary volume set is not recorded in the Backup Database and +exists only during the lifetime of the interactive session in which it is +created. +
New options to the backup deletedump command +
There are new options to the backup deletedump command: +the -groupid argument specifies the group ID number associated with +the dump records to delete, and the -noexecute flag displays a list +of the records to be deleted rather than actually deleting them. (There +are also new options that apply only to records for data dumped to an XBSA +server, as documented in New Command and File Features that Support TSM.) +
The new options are not documented in the IBM AFS Administration +Guide or IBM AFS Administration Reference. See backup deletedump. +
New output from the backup dumpinfo command +
When both the -id and -verbose options to the +backup dumpinfo command are provided, the output is divided into +several sections. In the first section, headed by the label +Dump, the new Group id field replaces the id +field that previously appeared about halfway down the list of fields (the +first field in the section is still labeled id). The +Group id field reports the dump's group ID number, which is +recorded in the Backup Database if the GROUPID instruction appears +in the Tape Coordinator's /usr/afs/backup/CFG_tcid +file when the dump is created. +
(The command's output also includes a new message that reports whether +the dump data is stored on an XBSA server, as detailed in New Command and File Features that Support TSM.) +
The new output is not documented in the IBM AFS Administration +Guide or IBM AFS Administration Reference. See backup dumpinfo. +
BOS Server sends additional field to notifier programs +
The AFS 3.6 BOS Server sends additional information to notifier +programs when an AFS server process exits. The bnode_proc +structure now includes the lastExit field, which reports the exit +code associated with the process's most recent exit. Previously, +the only information about exit codes available to the notifier program was in +the bnode structure's errorCode field, which +records the exit code generated when the process last exited due to an +error. The BOS Server does not clear the errorCode field, so +the value set at the last exit due to error is reported even for exits that +are not due to error. +
If your notifier program currently checks the errorCode field +but you really want a notification only when the most recent exit is due to an +error, change the program to check the lastExit field in the +bnode_proc structure instead. An error code appears in the +lastExit field only if the most recent exit really was due to an +error (in which case the same code also appears in the errorCode +field). +
The bos create command's reference page in the IBM AFS +Administration Reference describes all of the fields that the BOS Server +can include in the bnode_proc and bnode +structures. As noted there, the BOS Server does not necessarily include +every field in the structures it sends to a notifier program, because some of +them are for internal use. For best results, the notifier program must +correctly handle the absence of a field that it expects to find. +
Only administrators can use kas examine command's -showkey +flag +
As in AFS 3.5, the AFS 3.6 Authentication Server does not +require that you disable authorization checking on its database server machine +before it returns the octal digits that constitute the encrypted password or +key stored in an Authentication Database entry, which was the requirement with +earlier versions of AFS. Instead, it always returns the octal digits, +as long as the connection between the kas command interpreter and +Authentication Server is encrypted. AFS 3.5 introduced the +-showkey flag to make the kas examine command display +the octal digits. +
This change in requirements creates a potential security exposure, however, +in that earlier versions of the kas examine command always display +the octal digits (instead of a checksum) when directed to an AFS 3.5 or +3.6 Authentication Server. To eliminate this exposure, in AFS +3.6 the Authentication Server returns octal digits only for a principal +that has the ADMIN flag in its Authentication Database +entry. +
The main effect of the new requirement is that only administrators can +include the -showkey flag on the AFS 3.6 kas +examine command. It does not effectively change the privilege +required to display the octal digits when using versions of the kas +examine command before AFS 3.5 Patch 2 (build level +afs3.5 3.17), because it was assumed with earlier +versions that only administrators were able to disable authorization +checking. It also does not affect the automated installation and +configuration tool provided for AFS for Windows, which still can be used only +by administrators. +
The vos delentry command accepts only read/write volume names +
The AFS 3.6 version of the vos delentry command accepts +only read/write volume names or volume ID numbers as values for its +-id or -prefix arguments. The new restriction is +not documented in the IBM AFS Administration Guide or IBM AFS +Administration Reference. See vos delentry. +

Support for Backup to TSM

AFS 3.6 introduces support for backing up AFS data to +media managed by the Tivoli Storage Manager (TSM), a third-party backup +program which implements the Open Group's Backup Service application +programming interface (API), also called XBSA. TSM was +formerly called the ADSTAR Distributed Storage Manager, or ADSM. It is +assumed that the administrator is familiar with TSM; explaining TSM or +XBSA concepts or terminology is beyond the scope of this document. +

See the following subsections: +

New Command and File Features that Support TSM +
Product Notes for Use of TSM +
Configuring the Backup System and TSM +

New Command and File Features that Support TSM

The AFS 3.6 version of the following commands and +configuration files include new options or instructions to support backup to +TSM. +

New XBSA-related instructions in the CFG_tcid +file +
Several new or modified instructions in the CFG_tcid +file support backup of AFS data to XBSA servers such as TSM: +MGMTCLASS, NODE, PASSFILE, +PASSWORD, SERVER, and TYPE. (There are +also new instructions that apply to automated tape devices and backup data +files as well as XBSA servers, as detailed in New File or Command Functionality.) +
The new instructions are not documented in the IBM AFS Administration +Guide or IBM AFS Administration Reference. See CFG_tcid. (Note that this is a new way of referring to this +file, called CFG_device_name in the IBM AFS +Administration Guide and IBM AFS Administration +Reference. For a Tape Coordinator that communicates with XBSA +server such as TSM, the variable part of the filename is a port offset number +rather than a device name, so the more generic tcid is a better +description of possible values in this part of the filename.) +
New options to the backup deletedump command +
The backup deletedump command has new options that enable you to +delete dump records stored on an XBSA server such as TSM, as well as the +corresponding Backup Database records: +
- The -dbonly flag deletes Backup Database records without +attempting to delete the corresponding records stored on the XBSA +server. +
- The -force flag deletes Backup Database records even if it is +not possible to delete the corresponding records stored on the XBSA +server. +
- The -port argument identifies the Tape Coordinator that +communicates with the XBSA server on which to delete records. +
+
There are also two new options that apply to automated tape devices and +backup data files as well as XBSA servers, as detailed in New File or Command Functionality. +
The new options are not documented in the IBM AFS Administration +Guide or IBM AFS Administration Reference. See backup deletedump. +
New output from the backup dumpinfo command +
When the -id option is provided to the backup +dumpinfo command, the following line appears in the output if a TSM +server was the backup medium for the dump: +
```
   Backup Service: TSM: Server: hostname
+
```
+
where hostname is the name of the TSM server machine. +(There is also new output for dumps to all types of backup media, as detailed +in New File or Command Functionality.) +
The new output is not documented in the IBM AFS Administration +Guide or IBM AFS Administration Reference. See backup dumpinfo. +
New output from the backup status command +
If the Tape Coordinator is communicating with a TSM server, the following +message appears last in the output from the backup status +command: +
```
   TSM Tape coordinator
+
```
+
The new output is not documented in the IBM AFS Administration +Guide or IBM AFS Administration Reference. See backup status. +

Product Notes for Use of TSM

Supported Tape Coordinator machine types +
To communicate with a TSM server, the Tape Coordinator must run on a +machine that uses one of the following operating systems: AIX 4.3 +or higher, Solaris 2.6, Solaris 7. +
Supported version of TSM API +
The AFS 3.6 Tape Coordinator uses version 3.7.1 +(Version 3, Release 7) of the TSM client API. Use of other versions of +the API is not supported or tested. For instructions on obtaining the +API, see Configuring the Backup System and TSM. +
CFG_tcid file is required for TSM servers +
To communicate with a TSM server, a Tape Coordinator must have a +CFG_tcid file that includes the following fields: +SERVER, TYPE, and PASSWORD or +PASSFILE. For instructions on creating the file, see Configuring the Backup System and TSM. +
No entry in tapeconfig file for TSM servers +
Do not create an entry in the /usr/afs/backup/tapeconfig file +for a Tape Coordinator that communicates with an XBSA server such as +TSM. Creating the CFG_tcid file is +sufficient. +
Acceptable value for the TYPE instruction +
In AFS 3.6, there is one acceptable value for the TYPE +instruction in the CFG_tcid file: +tsm. +
TSM node name must be defined +
If the NODE instruction is not included in the +/usr/afs/backup/CFG_tcid file, the TSM +dsm.sys file must define a value for the NODENAME +variable. +
Unsupported backup commands and options +
The following commands are not supported for XBSA servers such as +TSM. In other words, the commands fail with an error message when their +-port argument specifies a Tape Coordinator that communicates with +an XBSA server: +
- backup labeltape +
- backup readlabel +
- backup restoredb +
- backup savedb +
- backup scantape +
+
In addition, the -append flag to the backup dump +command is ignored when the -port argument specifies a Tape +Coordinator that communicates with an XBSA server (the notion of appended +dumps does not apply to XBSA servers). +

Configuring the Backup System and TSM

Perform the following steps to configure TSM and the +AFS Backup System for interoperation. +
Note: You possibly need to perform additional TSM configuration procedures +unrelated to AFS. See the TSM documentation. +
+

Become the local superuser root, if you are not already. +
+
```
   % su root
+   Password: root_password   
+
```
+
Install version 3.7.1 of the TSM client API on the local +disk of the Tape Coordinator machine. If you do not already have the +API, you can use the following instructions to download it using the UNIX File +Transfer Protocol (ftp). +
1. Verify that there is enough free space on the local disk to accommodate +the API package: +
  - On AIX systems, 4 MB on the disk that houses the /usr/tivoli +directory +
  - On Solaris systems, 13 MB on the disk that houses the +/opt/tivoli directory +
  +
2. Connect to the ftp server called +ftp.software.ibm.com, logging in as +anonymous and providing your electronic mail address as the +password. +
3. Switch to binary mode. +
```
   ftp> bin   
+
```
  +
4. Change directory as indicated: +
```
   ftp> cd storage/tivoli-storage-management-maintenance/client/v3r7   
+
```
  +
5. Change to the appropriate directory and retrieve the API file. +
  - On an AIX 4.3 system: +
```
   ftp> cd AIX/v371
+   ftp> get tivoli.tsm.client.api.aix43.32bit   
+
```
    +
  - On a Solaris 2.6 or 7 system: +
```
   ftp> cd Solaris/v371
+   ftp> get IP21804.tar.Z   
+
```
    +
  +
6. Use the appropriate tool to install the TSM API package locally: +
  - On AIX machines, use smit, which installs the files in the +/usr/tivoli/tsm/client/api/bin directory +
  - On Solaris machines, use the following command, which installs the files +in the /opt/tivoli/tsm/client/api/bin directory: +
```
   # uncompress IP21804.tar.Z | tar xvf -   
+
```
    +
  +
+
Set the following TSM environment variables as indicated. If you do +not set them, you must use the default values specified in the TSM +documentation. +
+
DSMI_DIR +
Specifies the pathname of the directory that contains the TSM client +system options file, dsm.sys. The directory must have +a subdirectory (which can be a symbolic link) called en_US that +contains the dsmclientV3.cat catalog file. +
Do not put a final slash ( / ) on the directory name. +Examples of appropriate values are /opt/tivoli/tsm/client/api/bin +on Solaris machines and /usr/tivoli/tsm/client/api/bin on AIX +machines. +
DSMI_CONFIG +
Specifies the pathname of the directory that contains the TSM client user +options file, dsm.opt. The value can be the same as +for the DSMI_DIR variable. Do not put a final slash ( +/ ) on the directory name. +
DSMI_LOG +
Specifies the full pathname (including the filename) of the log file for +error messages from the API. An appropriate value is +/usr/afs/backup/butc.TSMAPI.log. +
+

Verify that the dsm.sys file includes the +following instructions. For a description of the fields, see the TSM +documentation. +

   ServerName           machine_name
+      CommMethod        tcpip
+      TCPPort           TSM_port
+      TCPServerAddress  full_machine_name
+      PasswordAccess    prompt
+      Compression       yes
+

The following is an example of appropriate values: +

   ServerName tsm3
+      CommMethod tcpip
+      TCPPort 1500
+      TCPServerAddress  tsm3.abc.com
+      PasswordAccess  prompt
+      Compression  yes   
+

Verify that the dsm.opt file includes the following +instructions. For a description of the fields, see the TSM +documentation. +
```
   ServerName        machine_name
+      tapeprompt     no
+      compressalways yes   
+
```
+
Create a Backup Database entry for each Tape +Coordinator that is to communicate with the TSM server. Multiple Tape +Coordinators can interact with the same TSM server if the server has +sufficient capacity. +
```
   # backup addhost <tape machine name> <TC port offset>
+
```
+
where +
+
tape machine name +
Specifies the fully qualified hostname of the Tape Coordinator +machine. +
TC port offset +
Specifies the Tape Coordinator's port offset number. +Acceptable values are integers in the range from 0 (zero) through +58510. +
+
Create a device configuration file for the Tape Coordinator called +/usr/afs/backup/CFG_tcid, where tcid is the Tape +Coordinator's port offset number as defined in Step 6. The file must include the following +instructions: +
- SERVER, which takes as its argument the fully qualified +hostname of the TSM server machine. It matches the value in the +full_machine_name field of the dsm.sys file, as +defined in Step 4. +
- TYPE, which takes as its argument the string tsm +(the only acceptable value in AFS 3.6). +
- One of PASSWORD or PASSFILE, to define the password +which the Tape Coordinator uses when communicating with the TSM server. +PASSWORD takes as its argument the actual password character +string. PASSFILE takes as its argument the complete pathname +of the file that contains the string on its first line. +
+
For more detailed descriptions of the instructions, and of other +instructions you can include in the configuration file, see CFG_tcid. +

Upgrading Server and Client Machines to AFS 3.6

This section explains how to upgrade server and client +machines from AFS 3.5 or AFS 3.6 Beta to AFS 3.6. +Before performing an upgrade, please read all of the introductory material in +this section. +

If you are installing AFS for the first time, skip this chapter and refer +to the IBM AFS Quick Beginnings document for AFS 3.6. +

AFS provides backward compatibility to the previous release only: AFS +3.6 is certified to be compatible with AFS 3.5 but not +necessarily with earlier versions. +
Note: This document does not provide instructions for upgrading from AFS +3.4a or earlier directly to AFS 3.6. A file system +conversion is required on some system types. See the AFS Release +Notes for AFS 3.5 and contact your AFS product support +representative for assistance. +
+

Prerequisites for Upgrading

You must meet the following requirements to upgrade successfully to AFS +3.6: +

You can access the AFS 3.6 binaries by network, or have the CD-ROM +labeled AFS Version 3.6 for each system type you need to +upgrade. See Obtaining the Binary Distribution. +
You have access to the IBM AFS Quick Beginnings document for +AFS 3.6, either in hardcopy (for English, IBM document number +SC09-4560-00, part number CT6Q7NA) or at <A +HREF="http://www.transarc.com/Library/documentation/afs_doc.html">http://www.transarc.com/Library/documentation/afs_doc.html</A>. +See also Accessing the AFS Binary Distribution and Documentation. +
The partition that houses the /usr/afs/bin directory on each +server machine has at least 18 MB of disk space for storing the AFS server +binaries. +
The partition that houses the /usr directory on each client +machine has at least 4 MB of disk space for storing the AFS client binaries +and kernel library files (stored by convention in the /usr/vice/etc +directory). +
You can log into all server and client machines as the local superuser +root. +
You are listed in the cell's /usr/afs/etc/UserList file +and can authenticate as a member of the system:administrators +group. +

Obtaining the Binary Distribution

Use one of the following methods to obtain the AFS +distribution of each system type for which you are licensed. +

Working with your AFS Sales Representative, obtain the AFS 3.6 +CD-ROM for each system type. +
Access the distribution by network in IBM's Electronic Software +Distribution system. +

Storing Binaries in AFS

It is conventional to store many of the programs and +files from the AFS binary distribution in a separate volume for each system +type, mounted in your AFS filespace at +/afs/cellname/sysname/usr/afsws. +These instructions rename the volume currently mounted at this location and +create a new volume for AFS 3.6 binaries. +

Repeat the instructions for each system type. +

Authenticate as an administrator listed in the +/usr/afs/etc/UserList file. +
Issue the vos create command to create a new volume for AFS +3.6 binaries called +sysname.3.6. Set an unlimited quota +on the volume to avoid running out of space as you copy files from the +distribution. +
```
   % vos create <machine name> <partition name> sysname.3.6  -maxquota  0    
+
```
+
Issue the fs mkmount command to mount the volume at a temporary +location. +
```
   % fs mkmount  /afs/.cellname/temp  sysname.3.6    
+
```
+
Prepare to access the files using the method you have selected: +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   % cd /cdrom/sysname    
+
```
  +
- If accessing the distribution electronically, download the necessary file +or files. If necessary, use commands such as gunzip and +tar xvf to uncompress and unpack the distribution. Place the +contents in a temporary location (temp_afs36_dir) and change +directory to that location. +
```
   %  cd  temp_afs36_dir    
+
```
  +
+

Copy files from the distribution into the +sysname.3.6 volume. +

   % cp -rp  bin  /afs/.cellname/temp  
+   
+   % cp -rp  etc  /afs/.cellname/temp  
+      
+   % cp -rp  include  /afs/.cellname/temp  
+   
+   % cp -rp  lib  /afs/.cellname/temp   
+

(Optional) By convention, the contents of +the distribution's root.client directory are not stored +in AFS. However, if you are upgrading client functionality on many +machines, it can be simpler to copy the client files from your local AFS space +than from the CD-ROM or from IBM's Electronic Software Distribution +system. If you wish to store the contents of the +root.client directory in AFS temporarily, copy them +now. +
```
   % cp -rp  root.client  /afs/.cellname/temp  
+
```
+
Issue the vos rename command to change the name of the volume +currently mounted at the +/afs/cellname/sysname/usr/afsws +directory. A possible value for the extension reflects the AFS +version and build level (for example: +3.5-bld3.32). +
If you do not plan to retain the old volume, you can substitute the +vos remove command in this step. +
```
   %  vos rename sysname.usr.afsws  sysname.usr.afsws.extension    
+
```
+
Issue the vos rename command to change the name of the +sysname.3.6 volume to +sysname.usr.afsws. +
```
   %  vos rename sysname.3.6  sysname.usr.afsws    
+
```
+
Issue the fs rmmount command to remove the temporary mount +point for the sysname.3.6 volume. +
```
    % fs rmmount  /afs/.cellname/temp   
+
```
+

Upgrading the Operating System

AFS 3.6 supports the 64-bit version of HP-UX +11.0 and Solaris 7. To upgrade from the 32-bit version, +you possibly need to reinstall the operating system completely before +installing AFS 3.6. When performing any operating system +upgrade, you must take several actions to preserve AFS functionality, +including the following: +

Unmount the AFS server partitions (those mounted on /vicep +directories) on all file server machines, to prevent the standard vendor +version of the fsck program from running on them when you reboot +the machine during installation of the new operating system. On several +operating systems, the standard fsck program does not recognize AFS +volume data and discards it. Also, disable automatic mounting of the +partitions during reboot until you have substituted the AFS vfsck +program for the vendor fsck program. +
Create copies of the AFS-modified versions of binaries or files so that +they are not overwritten by the standard versions during the operating system +upgrade, particularly if you are not performing an immediate AFS +upgrade. Examples include the remote commands (ftpd, +inetd, rcp, rsh, and so on) and the +vfsck binary. After you have successfully installed the new +version of the operating system, move the AFS-modified files and commands back +to the directories from which they are accessed during normal use. +

Distributing Binaries to Server Machines

The instructions in this section explain how to use the +Update Server to distribute server binaries from a binary distribution machine +of each system type. +

Repeat the steps on each binary distribution machine in your cell. +If you do not use the Update Server, repeat the steps on every server machine +in your cell. If you are copying files from the AFS product tree, the +server machine must also be configured as an AFS client machine. +

Become the local superuser root, if you are not already. +
+
```
   % su root
+   Password: root_password   
+
```
+
Create a temporary subdirectory of the /usr/afs/bin directory +to store the AFS 3.6 server binaries. +
```
   # mkdir /usr/afs/bin.36    
+
```
+
Prepare to access server files using the method you have selected from +those listed in Obtaining the Binary Distribution: +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.server/usr/afs/bin    
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.server/usr/afs/bin     
+
```
  +
+
Copy the server binaries from the distribution into the +/usr/afs/bin.36 directory. +
```
   # cp -p  *  /usr/afs/bin.36   
+
```
+
Rename the current /usr/afs/bin directory +to /usr/afs/bin.old and the +/usr/afs/bin.36 directory to the standard location. +
```
   # cd /usr/afs
+   
+   # mv  bin  bin.old
+      
+   # mv  bin.36  bin   
+
```
+

Upgrading Server Machines

Repeat the following instructions on each server +machine. Perform them first on the database server machine with the +lowest IP address, next on the other database server machines, and finally on +other server machines. +

The AFS data stored on a server machine is inaccessible to client machines +during the upgrade process, so it is best to perform it at the time and in the +manner that disturbs your users least. +

If you have just followed the steps in Distributing Binaries to Server Machines to install the server binaries on binary distribution +machines, wait the required interval (by default, five minutes) for the local +upclientbin process to retrieve the binaries. +
If you do not use binary distribution machines, perform the instructions in +Distributing Binaries to Server Machines on this machine. +
Become the local superuser root, if you are not already, by +issuing the su command. +
```
   % su root
+   Password: root_password   
+
```
+
If the machine also functions as a client machine, prepare to access +client files using the method you have selected from those listed in Obtaining the Binary Distribution: +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+

If the machine also functions as a client machine, copy the AFS 3.6 +version of the afsd binary and other files to the +/usr/vice/etc directory. +

Note:

Some files in the /usr/vice/etc directory, such as the AFS +initialization file (called afs.rc on many system types), do +not necessarily need to change for a new release. It is a good policy +to compare the contents of the distribution directory and the +/usr/vice/etc directory before performing the copying +operation. If there are files in the /usr/vice/etc directory +that you created for AFS 3.5 or 3.6 Beta and that you want to +retain, either move them to a safe location before performing the following +instructions, or alter the following instructions to copy over only the +appropriate files. +

   # cp  -p  usr/vice/etc/*   /usr/vice/etc   
+   
+   # cp  -rp  usr/vice/etc/C  /usr/vice/etc   
+

If you have not yet incorporated AFS into the machine's authentication +system, perform the instructions in the section titled Enabling AFS +Login for this system type in the IBM AFS Quick Beginnings +chapter about configuring client machines. If this machine was running +the same operating system revision with AFS 3.5 or AFS 3.6 Beta, +you presumably already incorporated AFS into its authentication system. +

AFS performance is most dependable if the AFS release version of the +kernel extensions and server processes is the same. Therefore, it is +best to incorporate the AFS 3.6 kernel extensions into the kernel at +this point. +
First issue the following command to shut down the server processes, +preventing them from restarting accidently before you incorporate the AFS +3.6 extensions into the kernel. +
```
   # bos shutdown <machine name> -localauth -wait
+
```
+
Then perform the instructions in Incorporating AFS into the Kernel and Enabling the AFS Initialization Script, which have you reboot the machine. Assuming that the +machine's AFS initialization script is configured to invoke the +bosserver command as specified in IBM AFS Quick +Beginnings, the BOS Server starts itself and then the other AFS server +processes listed in its local /usr/afs/local/BosConfig file. +
There are two circumstances in which you must incorporate the kernel +extensions and reboot now rather than later: +
- You are upgrading the File Server on an HP-UX machine +
- The machine also serves as a client, you upgraded the client files in the +previous step, and you want the new Cache Manager to become operative right +away +
+
In any other circumstances, you can choose to upgrade the kernel extensions +later. Choose one of the following options: +
- Restart all server processes by issuing the bos restart command +with the -bosserver flag. +
```
   # bos restart <machine name> -localauth -bosserver   
+
```
  +
- Wait to start using the new binaries until the processes restart +automatically at the binary restart time specified in the +/usr/afs/local/BosConfig file. +
+
Once you are satisfied that the machine is functioning +correctly at AFS 3.6, there is no need to retain previous versions of +the server binaries in the /usr/afs/bin directory. (You can +always use the bos install command to reinstall them if it becomes +necessary to downgrade). If you use the Update Server, the +upclientbin process renamed them with a .old +extension in Step 1. To reclaim the disk space occupied in the +/usr/afs/bin directory by .bak and +.old files, you can use the following command: +
```
   # bos prune <machine name> -bak -old -localauth
+
```
+
Step 5 of Distributing Binaries to Server Machines had you move the previous version of the +binaries to the /usr/afs/bin.old directory. You can +also remove that directory on any machine where you created it. +
```
   # rm -rf  /usr/afs/bin.old   
+
```
+

Upgrading Client Machines

Become the local superuser root, if you are not already, by +issuing the su command. +
```
   % su root
+   Password: root_password   
+
```
+
Prepare to access client files using the method you have selected from +those listed in Obtaining the Binary Distribution: +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+

Copy the AFS 3.6 version of the afsd binary and other +files to the /usr/vice/etc directory. +

Note:

   # cp  -p  usr/vice/etc/*   /usr/vice/etc   
+   
+   # cp  -rp  usr/vice/etc/C  /usr/vice/etc   
+

Perform the instructions in Incorporating AFS into the Kernel and Enabling the AFS Initialization Script to incorporate AFS extensions into the kernel. The +instructions conclude with a reboot of the machine, which starts the new Cache +Manager. +

Incorporating AFS into the Kernel and Enabling the AFS Initialization Script

As part of upgrading a machine to AFS 3.6, you must +incorporate AFS 3.6 extensions into its kernel and verify that the AFS +initialization script is included in the machine's startup +sequence. Proceed to the instructions for your system type: +

Loading AFS into the AIX Kernel +
Building AFS into the Digital UNIX Kernel +
Building AFS into the HP-UX Kernel +
Incorporating AFS into the IRIX Kernel +
Loading AFS into the Linux Kernel +
Loading AFS into the Solaris Kernel +

Loading AFS into the AIX Kernel

The AIX kernel extension facility is the dynamic kernel +loader provided by IBM Corporation. AIX does not support incorporation +of AFS modifications during a kernel build. +

After editing the script, you verify that there is an entry in the AIX +inittab file that invokes it, then reboot the machine to +incorporate the new AFS extensions into the kernel and restart the Cache +Manager. +

Access the AFS distribution by changing directory as indicated. +Substitute rs_aix42 for the sysname variable. +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+
Copy the AFS kernel library files to the local +/usr/vice/etc/dkload directory. +
```
   # cd  usr/vice/etc
+   
+   # cp -rp  dkload  /usr/vice/etc   
+
```
+
Because you ran AFS 3.5 on this machine, the appropriate AFS +initialization file possibly already exists as +/etc/rc.afs. Compare it to the version in the +root.client/usr/vice/etc directory of the AFS 3.6 +distribution to see if any changes are needed. +
If the initialization file is not already in place, copy it now. +
```
   # cp -p  rc.afs  /etc/rc.afs    
+
```
+
Edit the /etc/rc.afs script, setting the NFS +variable if it is not already. +
- If the machine is not to function as an NFS/AFS Translator, set the NFS +variable as follows: +
```
   NFS=$NFS_NONE   
+
```
  +
- If the machine is to function as an NFS/AFS Translator and is running AIX +4.2.1 or higher, set the NFS variable as follows. Only +sites that have a license for the NFS/AFS Translator are allowed to run +translator machines. Machines running the base level of AIX 4.2 +cannot be translator machines. +
  NFS must already be loaded into the kernel. It is loaded +automatically on machines running AIX 4.1.1 and later, as long +as the file /etc/exports exists. +
```
   NFS=$NFS_IAUTH   
+
```
  +
+
Place the following line in the AIX initialization file, +/etc/inittab, if it is not already. It invokes the AFS +initialization script and needs to appear just after the line that starts NFS +daemons. +
```
   rcafs:2:wait:/etc/rc.afs > /dev/console 2>&1 # Start AFS services   
+
```
+
(Optional) There are now copies of the AFS initialization file +in both the /usr/vice/etc and /etc directories. +If you want to avoid potential confusion by guaranteeing that they are always +the same, create a link between them. You can always retrieve the +original script from the AFS distribution if necessary. +
```
   # cd  /usr/vice/etc
+   
+   # rm  rc.afs
+  
+   # ln -s  /etc/rc.afs   
+
```
+
Reboot the machine. +
```
      # shutdown -r now   
+
```
+
If you are upgrading a server machine, login again as the local superuser +root, then return to Step 6 in Upgrading Server Machines. +
```
   login: root
+   Password: root_password     
+
```
+

Building AFS into the Digital UNIX Kernel

On Digital UNIX machines, you must build AFS +modifications into a new static kernel; Digital UNIX does not support +dynamic loading. If the machine's hardware and software +configuration exactly matches another Digital UNIX machine on which AFS +3.6 is already built into the kernel, you can choose to copy the kernel +from that machine to this one. In general, however, it is better to +build AFS modifications into the kernel on each machine according to the +following instructions. +

If the machine was running a version of Digital UNIX 4.0 with a +previous version of AFS, the configuration changes specified in Step 1 through Step 4 are presumably already in place. +

Create a copy called AFS of the basic kernel +configuration file included in the Digital UNIX distribution as +/usr/sys/conf/machine_name, where machine_name is +the machine's hostname in all uppercase letters. +
```
   # cd /usr/sys/conf
+   
+   # cp machine_name AFS   
+
```
+

Add AFS to the list of options in the configuration file you created in +the previous step, so that the result looks like the following: +

          .                   .
+          .                   .
+       options               UFS
+       options               NFS
+       options               AFS
+          .                   .
+          .                   .   
+

Add an entry for AFS to two places in the /usr/sys/conf/files +file. +

Add a line for AFS to the list of OPTIONS, so that the result +looks like the following: +

             .              .        .
+             .              .        .
+      OPTIONS/nfs        optional nfs define_dynamic
+      OPTIONS/afs        optional afs define_dynamic
+      OPTIONS/cdfs       optional cdfs define_dynamic
+             .              .        .
+             .              .        .   
+

Add an entry for AFS to the list of MODULES, so that the result +looks like the following: +

             .            .        .          .
+             .            .        .          .
+      #
+      MODULE/nfs_server		optional nfs_server Binary
+      nfs/nfs_server.c		module nfs_server optimize -g3
+      nfs/nfs3_server.c		module nfs_server optimize -g3
+      #
+      MODULE/afs		optional afs Binary
+      afs/libafs.c		module afs
+      #   
+

Add an entry for AFS to two places in the +/usr/sys/vfs/vfs_conf.c file. +

Add AFS to the list of defined file systems, so that the result looks like +the following: +

        .       .              
+        .       .              
+     #include <afs.h>
+     #if defined(AFS) && AFS
+            extern struct vfsops afs_vfsops;
+     #endif  
+        .       .              
+        .       .                 
+

Put a declaration for AFS in the vfssw[] table's +MOUNT_ADDON slot, so that the result looks like the following: +

        .                          .              .
+        .                          .              .
+      &fdfs_vfsops,         "fdfs",   /* 12 = MOUNT_FDFS */
+   #if	defined(AFS)
+      &afs_vfsops,          "afs",
+   #else
+      (struct vfsops *)0,   "",       /* 13 = MOUNT_ADDON */
+   #endif
+   #if NFS && INFS_DYNAMIC   
+       &nfs3_vfsops,        "nfsv3",  /* 14 = MOUNT_NFS3 */   
+

Access the AFS distribution by changing directory as indicated. +Substitute alpha_dux40 for the sysname variable. +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+
Because you ran AFS 3.5 on this machine, the appropriate AFS +initialization file possibly already exists as +/sbin/init.d/afs. Compare it to the version in the +root.client/usr/vice/etc directory of the AFS 3.6 +distribution to see if any changes are needed. +
If the initialization file is not already in place, copy it now. +Note the removal of the .rc extension as you copy. +
```
    # cp  -p  usr/vice/etc/afs.rc  /sbin/init.d/afs   
+
```
+
Copy the AFS kernel module to the local /usr/sys/BINARY +directory. +
The AFS 3.6 distribution includes only the +libafs.nonfs.o version of the library, because +Digital UNIX machines are not supported as NFS/AFS Translator machines. +
```
   # cp  -p  bin/libafs.nonfs.o  /usr/sys/BINARY/afs.mod   
+
```
+
Configure and build the kernel. Respond to any prompts by pressing +<Return>. The resulting kernel is in the file +/sys/AFS/vmunix. +
```
   # doconfig -c AFS   
+
```
+
Rename the existing kernel file and copy the new, AFS-modified file to the +standard location. +
```
   # mv  /vmunix  /vmunix_orig
+   
+   # cp  -p  /sys/AFS/vmunix  /vmunix   
+
```
+
Verify the existence of the symbolic links specified in the following +commands, which incorporate the AFS initialization script into the Digital +UNIX startup and shutdown sequence. If necessary, issue the commands to +create the links. +
```
   # ln -s  ../init.d/afs  /sbin/rc3.d/S67afs
+   
+   # ln -s  ../init.d/afs  /sbin/rc0.d/K66afs   
+
```
+
(Optional) If the machine is configured as a client, there are +now copies of the AFS initialization file in both the /usr/vice/etc +and /sbin/init.d directories. If you want to avoid +potential confusion by guaranteeing that they are always the same, create a +link between them. You can always retrieve the original script from the +AFS distribution if necessary. +
```
   # cd  /usr/vice/etc
+   
+   # rm  afs.rc
+  
+   # ln -s  /sbin/init.d/afs  afs.rc   
+
```
+
Reboot the machine. +
```
   # shutdown -r now   
+
```
+
If you are upgrading a server machine, login again as the local superuser +root, then return to Step 6 in Upgrading Server Machines. +
```
   login: root
+   Password: root_password     
+
```
+

Building AFS into the HP-UX Kernel

On HP-UX machines, you must build AFS modifications into a +new kernel; HP-UX does not support dynamic loading. If the +machine's hardware and software configuration exactly matches another +HP-UX machine on which AFS 3.6 is already built into the kernel, you +can choose to copy the kernel from that machine to this one. In +general, however, it is better to build AFS modifications into the kernel on +each machine according to the following instructions. +

Move the existing kernel-related files to a safe location. +

   # cp -p  /stand/vmunix  /stand/vmunix.noafs
+   
+   # cp -p  /stand/system  /stand/system.noafs   
+

Access the AFS distribution by changing directory as indicated. +Substitute hp_ux110 for the sysname variable. +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+
Because you ran AFS 3.5 on this machine, the appropriate AFS +initialization file possibly already exists as +/sbin/init.d/afs. Compare it to the version in the +root.client/usr/vice/etc directory of the AFS 3.6 +distribution to see if any changes are needed. +
If the initialization file is not already in place, copy it now. +Note the removal of the .rc extension as you copy. +
```
   # cp  -p  usr/vice/etc/afs.rc  /sbin/init.d/afs   
+
```
+
Copy the file afs.driver to the local +/usr/conf/master.d directory, changing its name to +afs as you do so. +
```
   # cp  -p  usr/vice/etc/afs.driver  /usr/conf/master.d/afs   
+
```
+
Copy the AFS kernel module to the local /usr/conf/lib +directory. +
HP-UX machines are not supported as NFS/AFS Translator machines, so AFS +3.6 includes only libraries called +libafs.nonfs.a (for the 32-bit version of +HP-UX) and libafs64.nonfs.a (for the 64-bit +version of HP-UX). Change the library's name to +libafs.a as you copy it. +
For the 32-bit version of HP-UX: +
```
   # cp  -p   bin/libafs.nonfs.a   /usr/conf/lib/libafs.a
+
```
+
For the 64-bit version of HP-UX: +
```
   # cp  -p  bin/libafs64.nonfs.a   /usr/conf/lib/libafs.a   
+
```
+
Verify the existence of the symbolic links specified in the following +commands, which incorporate the AFS initialization script into the HP-UX +startup and shutdown sequence. If necessary, issue the commands to +create the links. +
```
   # ln -s ../init.d/afs /sbin/rc2.d/S460afs
+  
+   # ln -s ../init.d/afs /sbin/rc2.d/K800afs   
+
```
+
(Optional) If the machine is configured as a client, there are +now copies of the AFS initialization file in both the /usr/vice/etc +and /sbin/init.d directories. If you want to avoid +potential confusion by guaranteeing that they are always the same, create a +link between them. You can always retrieve the original script from the +AFS distribution if necessary. +
```
   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /sbin/init.d/afs  afs.rc   
+
```
+
Incorporate the AFS driver into the kernel, either using the +SAM program or a series of individual commands. Both methods +reboot the machine, which loads the new kernel and starts the Cache +Manager. +
- To use the SAM program: +
  1. Invoke the SAM program, specifying the hostname of the local +machine as local_hostname. The SAM graphical user +interface pops up. +
```
    # sam -display local_hostname:0   
+
```
    +
  2. Choose the Kernel Configuration icon, then the +Drivers icon. From the list of drivers, select +afs. +
  3. Open the pull-down Actions menu and choose the Add Driver +to Kernel option. +
  4. Open the Actions menu again and choose the Create a New +Kernel option. +
  5. Confirm your choices by choosing Yes and OK when +prompted by subsequent pop-up windows. The SAM program +builds the kernel and reboots the system. +
  6. Login again as the superuser root. +
```
   login: root
+   Password: root_password   
+
```
    +
  +
- To use individual commands: +
  1. Edit the file /stand/system, adding an entry for afs +to the Subsystems section. +
  2. Change to the /stand/build directory and issue the +mk_kernel command to build the kernel. +
```
   # cd /stand/build
+      
+   # mk_kernel   
+
```
    +
  3. Move the new kernel to the standard location (/stand/vmunix), +reboot the machine to start using it, and login again as the superuser +root. +
```
   # mv /stand/build/vmunix_test /stand/vmunix
+      
+   # cd /
+      
+   # shutdown -r now		
+   
+   login: root
+   Password: root_password   
+
```
    +
  +
+
If you are upgrading a server machine, login again as the local superuser +root, then return to Step 6 in Upgrading Server Machines. +
```
   login: root
+   Password: root_password     
+
```
+

Incorporating AFS into the IRIX Kernel

To incorporate AFS into the kernel on IRIX machines, +choose one of two methods: +

Dynamic loading using the ml program distributed by Silicon +Graphics, Incorporated (SGI). +
Building a new static kernel. Proceed to Building AFS into the IRIX Kernel. +

Loading AFS into the IRIX Kernel

The ml program is the dynamic kernel loader provided by SGI +for IRIX systems. If you use it rather than building AFS modifications +into a static kernel, then for AFS to function correctly the ml +program must run each time the machine reboots. Therefore, the AFS +initialization script (included on the AFS CD-ROM) invokes it automatically +when the afsml configuration variable is activated. In this +section you activate the variable and run the script. +

Issue the uname -m command to determine the machine's CPU +type. The IPxx value in the output must match one +of the supported CPU types listed in Supported System Types. +
```
   # uname -m   
+
```
+
Access the AFS distribution by changing directory as indicated. +Substitute sgi_65 for the sysname variable. +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+
Copy the appropriate AFS kernel library file to the local +/usr/vice/etc/sgiload directory; the IPxx +portion of the library file name must match the value returned by the +uname -m command. Also choose the file appropriate to +whether the machine's kernel supports NFS server functionality (NFS must +be supported for the machine to act as an NFS/AFS Translator). Single- +and multiprocessor machines use the same library file. +
You can choose to copy all of the kernel library files into the +/usr/vice/etc/sgiload directory, but they require a significant +amount of space. +
```
   # cd  usr/vice/etc/sgiload    
+
```
+
If the machine is not to act as an NFS/AFS translator: +
```
   # cp -p  libafs.IPxx.nonfs.o  /usr/vice/etc/sgiload   
+
```
+
If the machine is to act as an NFS/AFS translator, in which case its kernel +must support NFS server functionality: +
```
   # cp -p   libafs.IPxx.o   /usr/vice/etc/sgiload   
+
```
+
Proceed to Enabling the AFS Initialization Script on IRIX Systems. +

Building AFS into the IRIX Kernel

If you prefer to build a kernel, and the machine's +hardware and software configuration exactly matches another IRIX machine on +which AFS 3.6 is already built into the kernel, you can choose to copy +the kernel from that machine to this one. In general, however, it is +better to build AFS modifications into the kernel on each machine according to +the following instructions. +

Access the AFS distribution by changing directory as indicated. +Substitute sgi_65 for the sysname variable. +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+
Issue the uname -m command to determine the machine's CPU +type. The IPxx value in the output must match one +of the supported CPU types listed in the IBM AFS Release Notes for +the current version of AFS. +
```
   # uname -m    
+
```
+
Copy the appropriate AFS kernel library file to the local file +/var/sysgen/boot/afs.a; the IPxx +portion of the library file name must match the value returned by the +uname -m command. Also choose the file appropriate to +whether the machine's kernel supports NFS server functionality (NFS must +be supported for the machine to act as an NFS/AFS Translator). Single- +and multiprocessor machines use the same library file. +
```
   # cd  bin   
+
```
+
If the machine is not to act as an NFS/AFS translator: +
```
   # cp -p  libafs.IPxx.nonfs.a   /var/sysgen/boot/afs.a   
+
```
+
If the machine is to act as an NFS/AFS translator, in which case its kernel +must support NFS server functionality: +
```
   # cp -p   libafs.IPxx.a   /var/sysgen/boot/afs.a   
+
```
+
Copy the kernel initialization file afs.sm to the local +/var/sysgen/system directory, and the kernel master file +afs to the local /var/sysgen/master.d +directory. +
```
   # cp -p  afs.sm  /var/sysgen/system
+   
+   # cp -p  afs  /var/sysgen/master.d   
+
```
+
Copy the existing kernel file, /unix, to a safe location and +compile the new kernel. It is created as +/unix.install, and overwrites the existing /unix +file when the machine reboots. +
```
   # cp -p  /unix  /unix_orig
+   
+   # autoconfig   
+
```
+
Proceed to Enabling the AFS Initialization Script on IRIX Systems. +

Enabling the AFS Initialization Script on IRIX Systems

Because you ran AFS 3.5 on this machine, the appropriate AFS +initialization file possibly already exists as +/etc/init.d/afs. Compare it to the version in the +root.client/usr/vice/etc directory of the AFS 3.6 +distribution to see if any changes are needed. +
If the initialization file is not already in place, copy it now. If +the machine is configured as a client machine, you already copied the script +to the local /usr/vice/etc directory. Otherwise, change +directory as indicated, substituting sgi_65 for the +sysname variable. +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+
Now copy the script. Note the removal of the .rc +extension as you copy. +
```
   # cp -p  script_location/afs.rc  /etc/init.d/afs   
+
```
+
If the afsml configuration variable is not already set +appropriately, issue the chkconfig command. +
If you are using the ml program: +
```
   # /etc/chkconfig -f afsml on   
+
```
+
If you built AFS into a static kernel: +
```
   # /etc/chkconfig -f afsml off   
+
```
+
If the machine is to function as an NFS/AFS Translator, the kernel supports +NFS server functionality, and the afsxnfs variable is not already +set appropriately, set it now. +
```
   # /etc/chkconfig -f afsxnfs on   
+
```
+
Verify the existence of the symbolic links specified in the following +commands, which incorporate the AFS initialization script into the IRIX +startup and shutdown sequence. If necessary, issue the commands to +create the links. +
```
   # ln -s ../init.d/afs /etc/rc2.d/S35afs
+  
+   # ln -s ../init.d/afs /etc/rc0.d/K35afs   
+
```
+
(Optional) If the machine is configured as a client, there are +now copies of the AFS initialization file in both the /usr/vice/etc +and /etc/init.d directories. If you want to avoid +potential confusion by guaranteeing that they are always the same, create a +link between them. You can always retrieve the original script from the +AFS distribution if necessary. +
```
   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /etc/init.d/afs  afs.rc   
+
```
+
Reboot the machine. +
+
```
   # shutdown -i6 -g0 -y   
+
```
+
If you are upgrading a server machine, login again as the local superuser +root, then return to Step 6 in Upgrading Server Machines. +
```
   login: root
+   Password: root_password     
+
```
+

Loading AFS into the Linux Kernel

The insmod program is the dynamic kernel +loader for Linux. Linux does not support incorporation of AFS +modifications during a kernel build. +

Access the AFS distribution by changing directory as indicated. +Substitute i386_linux22 for the sysname variable. +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+
Copy the AFS kernel library files to the local +/usr/vice/etc/modload directory. The filenames for the +libraries have the format +libafs-version.o, where version +indicates the kernel build level. The string .mp in +the version indicates that the file is appropriate for use with +symmetric multiprocessor (SMP) kernels. +
```
   # cd  usr/vice/etc
+   
+   # cp -rp  modload  /usr/vice/etc   
+
```
+
The AFS 3.6 distribution includes a new AFS initialization file +that can select automatically from the kernel extensions included in AFS +3.6. Copy it to the /etc/rc.d/init.d +directory, removing the .rc extension as you do. +
```
   # cp -p   afs.rc  /etc/rc.d/init.d/afs    
+
```
+
The afsd options file possibly already exists as +/etc/sysconfig/afs from running a previous version of AFS on this +machine. Compare it to the version in the +root.client/usr/vice/etc directory of the AFS 3.6 +distribution to see if any changes are needed. +
If the options file is not already in place, copy it now. Note the +removal of the .conf extension as you copy. +
```
   # cp  -p  afs.conf  /etc/sysconfig/afs    
+
```
+
If necessary, edit the options file to invoke the desired arguments on the +afsd command in the initialization script. For further +information, see the section titled Configuring the Cache Manager +in the IBM AFS Quick Beginnings chapter about configuring client +machines. +
Issue the chkconfig command to activate the afs +configuration variable, if it is not already. Based on the instruction +in the AFS initialization file that begins with the string +#chkconfig, the command automatically creates the symbolic links +that incorporate the script into the Linux startup and shutdown +sequence. +
```
   # /sbin/chkconfig  --add afs   
+
```
+
(Optional) If the machine is configured as a client, there are +now copies of the AFS initialization file in both the /usr/vice/etc +and /etc/init.d directories, and copies of the +afsd options file in both the /usr/vice/etc and +/etc/sysconfig directories. If you want to avoid potential +confusion by guaranteeing that the two copies of each file are always the +same, create a link between them. You can always retrieve the original +script or options file from the AFS distribution if necessary. +
```
   # cd /usr/vice/etc
+   
+   # rm afs.rc afs.conf
+    
+   # ln -s  /etc/rc.d/init.d/afs  afs.rc
+   
+   # ln -s  /etc/sysconfig/afs  afs.conf   
+
```
+
Reboot the machine. +
```
   # shutdown -r now     
+
```
+
If you are upgrading a server machine, login again as the local superuser +root, then return to Step 6 in Upgrading Server Machines. +
```
   login: root
+   Password: root_password     
+
```
+

Loading AFS into the Solaris Kernel

The modload program is the dynamic kernel +loader provided by Sun Microsystems for Solaris systems. Solaris does +not support incorporation of AFS modifications during a kernel build. +

Access the AFS distribution by changing directory as indicated. +Substitute sun4x_56 or sun4x_57 for the sysname +variable. +
- If you copied the contents of the root.client directory +into AFS (in Step 6 of Storing Binaries in AFS), change directory as indicated. +
```
   # cd /afs/cellname/sysname/usr/afsws/root.client    
+
```
  +
- If copying files from the CD-ROM, mount the CD-ROM for this machine's +system type on the local /cdrom directory. For instructions +on mounting CD-ROMs (either locally or remotely via NFS), consult the +operating system documentation. Then change directory as +indicated. +
```
   # cd /cdrom/sysname/root.client     
+
```
  +
- If accessing the distribution electronically, you possibly already +downloaded it in Storing Binaries in AFS. If so, it is still in the temp_afs36_dir +directory. If not, download it and run any commands necessary to +uncompress or unpack the distribution. Place it in a temporary location +(temp_afs36_dir), and change directory to the indicated +subdirectory. +
```
   # cd  temp_afs36_dir/root.client     
+
```
  +
+
If this machine is running Solaris 2.6 or the 32-bit version +of Solaris 7, and ran that operating system with AFS 3.5, the +appropriate AFS initialization file possibly already exists as +/etc/init.d/afs. Compare it to the version in the +root.client/usr/vice/etc directory of the AFS 3.6 +distribution to see if any changes are needed. +
If this machine is running the 64-bit version of Solaris 7, the AFS +initialization file differs from the AFS 3.5 version. Copy it +from the AFS 3.6 distribution. +
Note the removal of the .rc extension as you copy. +
```
   # cd  usr/vice/etc
+    
+   # cp  -p  afs.rc  /etc/init.d/afs   
+
```
+
Copy the appropriate AFS kernel library file to the appropriate file in a +subdirectory of the local /kernel/fs directory. +
If the machine is running Solaris 2.6 or the 32-bit version of +Solaris 7 and is not to act as an NFS/AFS translator: +
```
   # cp  -p  modload/libafs.nonfs.o  /kernel/fs/afs   
+
```
+
If the machine is running Solaris 2.6 or the 32-bit version of +Solaris 7 and is to act as an NFS/AFS translator, in which case its kernel +must support NFS server functionality and the nfsd process must be +running: +
```
   # cp  -p  modload/libafs.o  /kernel/fs/afs   
+
```
+
If the machine is running the 64-bit version of Solaris 7 and is not +to act as an NFS/AFS translator: +
```
   # cp  -p  modload/libafs64.nonfs.o  /kernel/fs/sparcv9/afs   
+
```
+
If the machine is running the 64-bit version of Solaris 7 and is to +act as an NFS/AFS translator, in which case its kernel must support NFS server +functionality and the nfsd process must be running: +
```
   # cp  -p  modload/libafs64.o  /kernel/fs/sparcv9/afs      
+
```
+
Verify the existence of the symbolic links specified in the following +commands, which incorporate the AFS initialization script into the Solaris +startup and shutdown sequence. If necessary, issue the commands to +create the links. +
```
   # ln -s ../init.d/afs /etc/rc3.d/S99afs
+  
+   # ln -s ../init.d/afs /etc/rc0.d/K66afs   
+
```
+
(Optional) If the machine is configured as a client, there are +now copies of the AFS initialization file in both the /usr/vice/etc +and /etc/init.d directories. If you want to avoid +potential confusion by guaranteeing that they are always the same, create a +link between them. You can always retrieve the original script from the +AFS distribution if necessary. +
```
   # cd /usr/vice/etc
+   
+   # rm afs.rc
+  
+   # ln -s  /etc/init.d/afs  afs.rc   
+
```
+
Reboot the machine. +
```
   # shutdown -i6 -g0 -y      
+
```
+
If you are upgrading a server machine, login again as the local superuser +root, then return to Step 6 in Upgrading Server Machines. +
```
   login: root
+   Password: root_password     
+
```
+

Storing AFS Documents in AFS

This section explains how to create and mount a volume to +house AFS documents. The recommended mount point for the volume is +/afs/cellname/afsdoc. If you ran AFS +3.5, the volume possibly already exists. You can choose to +overwrite its contents with the AFS 3.6 version of documents, or can +create a new volume for the AFS 3.6 documents and mount it at +/afs/cellname/afsdoc instead of the volume of +AFS 3.5 documents. Alter the following instructions as +necessary. +

If you wish, you can create a link to the mount point on each client +machine's local disk, called /usr/afsdoc. +Alternatively, you can create a link to the mount point in each user's +home directory. You can also choose to permit users to access only +certain documents (most probably, the IBM AFS User Guide) by +creating different mount points or setting different ACLs on different +document directories. +

To create a new volume for storing AFS documents: +

Issue the vos create command to create a volume for storing the +AFS documentation. Include the -maxquota argument to set an +unlimited quota on the volume. +
If you wish, you can set the volume's quota to a finite value after +you complete the copying operations. At that point, use the vos +examine command to determine how much space the volume is +occupying. Then issue the fs setquota command to set a quota +value that is slightly larger. +
```
   % vos create <machine name> <partition name>  afsdoc  -maxquota 0     
+
```
+
Issue the fs mkmount command to mount the new volume. If +your root.cell volume is replicated, you must precede the +cellname with a period to specify the read/write mount point, as +shown. Then issue the vos release command to release a new +replica of the root.cell volume, and the fs +checkvolumes command to force the local Cache Manager to access +them. +
```
   % fs mkmount -dir /afs/.cellname/afsdoc -vol afsdoc
+   
+   % vos release root.cell
+   
+   % fs checkvolumes    
+
```
+
Issue the fs setacl command to grant the rl +permissions to the system:anyuser group on the new +directory's ACL. +
```
   % cd /afs/.cellname/afsdoc 
+    
+   % fs setacl  .  system:anyuser rl   
+
```
+
Access the documents via one of the sources listed in Accessing the AFS Binary Distribution and Documentation. Copy the documents in one more formats from a +source_format directory into subdirectories of the +/afs/cellname/afsdoc directory. Repeat +the commands for each format. Suggested substitutions for the +format_name variable are HTML and PDF. +
```
   # mkdir format_name
+   
+   # cd  format_name
+   
+   # cp -rp /cdrom/Documentation/language_code/source_format  .      
+
```
+
If you copy the HTML version of the documents, note that in addition to a +subdirectory for each document there are several files with a +.gif extension, which enable readers to move easily between +sections of a document. The file called index.htm is +an introductory HTML page that has a hyperlink to the documents. For +HTML viewing to work properly, these files must remain in the top-level HTML +directory (the one named, for example, +/afs/cellname/afsdoc/Html). +
(Optional) If you believe it is helpful to your users to access +AFS documents via a local disk directory, create /usr/afsdoc on the +local disk as a symbolic link to the directory housing the desired format +(probably HTML or PDF). +
```
   # ln -s /afs/cellname/afsdoc/format_name  /usr/afsdoc
+
```
+
An alternative is to create a link in each user's home directory to +the documentation directory in AFS. +

Reference Pages

Following are reference pages that include new +information not included in IBM AFS Administration +Reference. +

CFG_tcid

Purpose +

Defines Tape Coordinator configuration instructions for automated tape +devices, backup data files, or XBSA server programs +

Description +

A CFG_tcid file includes instructions that configure a +Tape Coordinator for more automated operation and for transferring AFS data to +and from a certain type of backup media: +

An automated tape device, such as a stacker or jukebox. The file is +optional for a Tape Coordinator that writes to such a device, and unnecessary +if the default value for all types of instruction are appropriate for the +device. +
A backup data file on a local disk device. The +configuration file is mandatory and must include the FILE +instruction at least. +
A third-party backup utility that implements the Open Group's Backup +Service API (XBSA), hereafter referred to as an XBSA server. +The file is mandatory and must include the SERVER, TYPE, +and PASSFILE or PASSWORD instructions. The +General Availability release of AFS 3.6 can communicate with one XBSA +server, the Tivoli Storage Manager (TSM). +

The configuration file is in ASCII-format and must reside in the +/usr/afs/backup directory on the Tape Coordinator machine. +Each Tape Coordinator has its own configuration file (multiple Tape +Coordinators cannot use the same file), and only a single Tape Coordinator in +a cell can write to a given tape device or backup data file. Multiple +Tape Coordinators can interact with the same XBSA server if the server has +sufficient capacity, and in this case the configuration file for each Tape +Coordinator refers to the same XBSA server. +

The Tape Coordinator for a tape device or backup data file must also have +an entry in the Backup Database and in the +/usr/afs/backup/tapeconfig file on the Tape Coordinator +machine. The Tape Coordinator for an XBSA server has only an entry in +the Backup Database, not in the tapeconfig file. +

Naming the Configuration File +

For a Tape Coordinator that communicates with an XBSA server, the +tcid portion of the configuration file's name is the Tape +Coordinator's port offset number as defined in the Backup +Database. An example filename is CFG_22. +

For the Tape Coordinator for a tape device or backup data file, there are +two possible types of values for the tcid portion of the +filename. The Tape Coordinator first attempts to open a file with a +tcid portion that is the Tape Coordinator's port offset number +as defined in the Backup Database and tapeconfig file. If +there is no such file, the Tape Coordinator attempts to access a file with a +tcid portion that is based on the tape device's device name the +backup data file's filename. To enable the Tape Coordinator to +locate the file, construct the tcid portion of the filename 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. +

Summary of Instructions +

The following list briefly describes the instructions that can appear in a +configuration file. Each instruction appears on its own line, in any +order. Unless otherwise noted, the instructions apply to all backup +media (automated tape device, backup data file, and XBSA server). 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. +Does not apply to XBSA servers. +
BUFFERSIZE +: Sets the size of the memory buffer the Tape Coordinator uses when dumping +data to or restoring data from a backup medium. +
CENTRALLOG +: Names a log file in which to record a status message as each dump or +restore operation completes. The Tape Coordinator also writes to its +standard log and error files. +
FILE +: Determines whether the Tape Coordinator uses a backup data file as the +backup medium. +
GROUPID +: Sets an identification number recorded in the Backup Database for all +dumps performed by the Tape Coordinator. +
LASTLOG +: Controls whether the Tape Coordinator creates and writes to a separate log +file during its final pass through the set of volumes to be included in a +dump. +
MAXPASS +: Specifies how many times the Tape Coordinator attempts to access a volume +during a dump operation if the volume is inaccessible on the first attempt +(which is included in the count). +
MGMTCLASS +: Specifies which of an XBSA server's management classes to use, which +often indicates the type of backup medium the XBSA server uses. Applies +only to XBSA servers. +
MOUNT +: Identifies the file that contains routines for inserting tapes into a tape +device or controlling how the Tape Coordinator handles a backup data +file. Does not apply to XBSA servers. +
NAME_CHECK +: Controls whether the Tape Coordinator verifies that a tape or backup data +file has the expected name. Does not apply to XBSA servers. +
NODE +: Names which node associated with an XBSA server to use. Applies +only to XBSA servers. +
PASSFILE +: Names the file that contains the password or security code for the Tape +Coordinator to pass to an XBSA server. Applies only to XBSA +servers. +
PASSWORD +: Specifies the password or security code for the Tape Coordinator to pass +to an XBSA server. Applies only to XBSA servers. +
SERVER +: Names the XBSA server machine with which the Tape Coordinator +communicates. Applies only to XBSA servers. +
STATUS +: Controls how often the Tape Coordinator writes a status message in its +window during an operation. +
TYPE +: Defines which XBSA-compliant program (third-party backup utility) is +running on the XBSA server. Applies only to XBSA servers. +
UNMOUNT +: Identifies the file that contains routines for removing tapes from a tape +device or controlling how the Tape Coordinator handles a backup data +file. Does not apply to XBSA servers. +

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_tcid 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 its +/usr/afs/backup/TE_tcid 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}   
+

The BUFFERSIZE Instruction +

The BUFFERSIZE instruction takes an integer or decimal value, +and optionally units, in the following format: +

   BUFFERSIZE size[{k | K | m | M | g | G | t | T}]   
+

where size specifies the amount of memory the Tape Coordinator +allocates to use as a buffer during both dump and restore operations. +If size is a decimal number, the number of digits after the decimal +point must not translate to fractions of bytes. The default unit is +bytes, but use k or K to specify kilobytes, m +or M for megabytes, g or G for gigabytes, and +t or T for terabytes. There is no space between +the size value and the units letter. +

As the Tape Coordinator receives volume data from the Volume Server during +a dump operation, it gathers the specified amount of data in the buffer before +transferring the entire amount to the backup medium. Similarly, during +a restore operation the Tape Coordinator by default buffers data from the +backup medium before transferring the entire amount to the Volume Server for +restoration into the file system. +

The default buffer size is 16 KB, which is usually large enough to promote +tape streaming in a normal network configuration. If the network +connection between the Tape Coordinator machine and file server machines is +slow, it can help to increase the buffer size. +

For XBSA servers, the range of acceptable values is 1K through +64K. For tape devices and backup data files, the minimum +acceptable value is 16K, and if the specified value is not a +multiple of 16 KB, the Tape Coordinator automatically rounds it up to the next +such multiple. +

The CENTRALLOG Instruction +

The CENTRALLOG instruction takes a pathname as its argument, in +the following format: +

   CENTRALLOG  filename   
+

where filename is the full pathname of a local disk file in which +to record a status message as each dump or restore operation completes. +It is acceptable to have multiple Tape Coordinators write to the same log +file. Each Tape Coordinator also writes to its own standard error and +log files (the TE_tcid and TL_tcid +files in the /usr/afs/backup directory). This instruction is +always optional. +

The line for each dump operation has the following format: +

   task_ID   start_time   complete_time   duration  volume_set  \
+         success of total volumes dumped (data_dumped KB)   
+

The line for each restore operation has the following format: +

   task_ID   start_time   complete_time   duration  success of total volumes restored 
+

where +

task_ID +: Is the task identification number assigned to the operation by the Tape +Coordinator. The first digits in the number are the Tape +Coordinator's port offset number. +
start_time +: The time at which the operation started, in the format +month/day/year +hours:minutes:seconds. +
complete_time +: Is the time at which the operation completed, in the same format as the +start_time field. +
duration +: Is the amount of time it took to complete the operation, in the format +hours:minutes:seconds. +
volume_set +: Is the name of the volume set being dumped during this operation (for dump +operations only). +
success +: Is the number of volumes successfully dumped or restored. +
total +: Is the total number of volumes the Tape Coordinator attempted to dump or +restore. +
data_dumped +: Is the number of kilobytes of data transferred to the backup medium (for +dump operations only). +

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 and the SERVER instruction does +not appear in the configuration file, the Tape Coordinator uses a tape device +as the backup medium. If the SERVER instruction does appear, +the Tape Coordinator communicates with the XBSA server that it names. +This is the default behavior if the FILE instruction does not +appear in the file. +

When the value is YES, the Tape Coordinator uses a backup data +file on the local disk as the backup medium. If the file does not exist +when the Tape Coordinator attempts 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 is accidently +dumped to a tape device while the FILE instruction is set to +YES. (In the same way, if the FILE instruction is +set to NO and there is no SERVER instruction, 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's name in this +field. This configuration has a couple of advantages: +

It makes the tcid portion of the CFG_tcid, +TE_tcid, and TL_tcid 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. +
+

The GROUPID Instruction +

The GROUPID instruction takes an integer as its argument, in the +following format: +

   GROUPID integer   
+

where integer is in the range from 1 through +2147483647 (one less than 2 GB). The value is recorded in +the Backup Database record for each dump created by this Tape +Coordinator. It appears in the Group id field in the output +from the backup dumpinfo command when the command's +-verbose and -id options are provided. It can be +specified as the value of the -groupid argument to the backup +deletedump command to delete only records marked with the group +ID. This instruction is always optional. +

The LASTLOG Instruction +

The LASTLOG instruction takes a boolean value as its argument, +in the following format: +

   LASTLOG  {YES | NO}   
+

When the value is YES, the Tape Coordinator creates and writes +to a separate log file during the final pass through the volumes to be +included in a dump operation. The log file name is +/usr/afs/backup/TL_tcid.lp, where +tcid is either the Tape Coordinator's port offset number or a +value derived from the device name or backup data filename. +

When the value is NO, the Tape Coordinator writes to its +standard log files (the TE_tcid and +TL_tcid files in the /usr/afs/backup directory) +for all passes. This is the behavior if the instruction does not appear +in the file. +

The MAXPASS Instruction +

The MAXPASS instruction takes an integer as its argument, in the +following format: +

   MAXPASS integer   
+

where integer specifies how many times the Tape Coordinator +attempts to access a volume during a dump operation if the volume is +inaccessible on the first attempt (which is included in the count). +Acceptable values are in the range from 1 through +10. The default value is 2 if this instruction +does not appear in the file. +

The MGMTCLASS Instruction +

The MGMTCLASS instruction takes a character string as its +argument, in the following format: +

   MGMTCLASS class_name   
+

where class_name is the XBSA server's management class, which +often indicates the type of backup medium it is using. For a list of +the possible management classes, see the XBSA server documentation. +This instruction applies only to XBSA servers and is always optional; +there is no default value if it is omitted. +

The MOUNT Instruction +

The MOUNT instruction takes a pathname as its argument, in the +following format: +

   MOUNT filename   
+

where filename is the full pathname of an executable file on the +local disk that contains a shell script or program (for clarity, the following +discussion refers to scripts only). If the configuration file is for an +automated tape device, the script invokes the routine or command provided by +the device's manufacturer for mounting a tape (inserting it into the tape +reader). If the configuration file is for a backup data file, it can +instruct the Tape Coordinator to switch automatically to another backup data +file when the current one becomes full; for further discussion, see the +preceding description of the FILE instruction. This +instruction does not apply to XBSA servers. +

The administrator must write the script, including the appropriate routines +and logic. The AFS distribution does not include any scripts, although +an example appears in the following Examples section. The +command or routines invoked by the script inherit the local identity (UNIX +UID) and AFS tokens of the butc command's issuer. +

When the Tape Coordinator needs to mount a tape or access another backup +data file, it checks the configuration file for a MOUNT +instruction. If there is no 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 script. +

The Tape Coordinator passes the following parameters to the script +indicated by the MOUNT instruction, 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 generally matches the backup command +operation code used to initiate the operation (the following list notes the +exceptional cases) : +
- 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 or opened the backup data file. 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 or open the backup data file. The Tape Coordinator terminates the +operation. +
Any other code indicates that the routine was not able to access the +correct tape or backup data file. The Tape Coordinator prompts the +operator to insert the correct tape. +

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 there is no permanent name on the +label of the tape or backup data file, the Tape Coordinator checks the AFS +tape name on the label when dumping a volume in response to the backup +dump command. The AFS tape name must be <NULL> or +match the name that the backup dump operation constructs 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. This +instruction does not apply to XBSA servers. +

The NODE Instruction +

The NODE instruction takes a character string as its argument, +in the following format: +

   NODE node_name   
+

where node_name names the node associated with the XBSA server +named by the SERVER instruction. To determine if the XBSA +server uses nodes, see its documentation. This instruction applies only +to XBSA servers, and there is no default if it is omitted. However, TSM +requires that a NODENAME instruction appear in its dsm.sys +configuration file in that case. +

The PASSFILE Instruction +

The PASSFILE instruction takes a pathname as its argument, in +the following format: +

   PASSFILE filename   
+

where filename is the full pathname of a file on the local disk +that records the password for the Tape Coordinator to use when communicating +with the XBSA server. The password string must appear on the first line +in the file, and have a newline character only at the end. The mode +bits on the file must enable the Tape Coordinator to read it. +

This instruction applies only to XBSA servers, and either it or the +PASSWORD instruction must be provided along with the +SERVER instruction. (If both this instruction and the +PASSWORD instruction are included, the Tape Coordinator uses only +the one that appears first in the file.) +

The PASSWORD Instruction +

The PASSWORD instruction takes a character string as its +argument, in the following format: +

   PASSWORD string   
+

where string is the password for the Tape Coordinator to use when +communicating with the XBSA server. It must appear on the first line in +the file, and have a newline character only at the end. +

This instruction applies only to XBSA servers, and either it or the +PASSFILE instruction must be provided along with the +SERVER instruction. (If both this instruction and the +PASSFILE instruction are included, the Tape Coordinator uses only +the one that appears first in the file.) +

The SERVER Instruction +

The SERVER instruction takes a character string as its argument, +in the following format: +

   SERVER machine_name   
+

where machine_name is the fully qualified hostname of the machine +where an XBSA server is running. This instruction is required for XBSA +servers, and applies only to them. +

The STATUS Instruction +

The STATUS instruction takes an integer as its argument, in the +following format: +

   STATUS integer   
+

where integer expresses how often the Tape Coordinator writes a +status message to its window during an operation, in terms of the number of +buffers of data that have been dumped or restored. Acceptable values +range from 1 through 8192. The size of the +buffers is determined by the BUFFERSIZE instruction if it is +included. +

As an example, the value 512 means that the Tape Coordinator +writes a status message after each 512 buffers of data. It also writes +a status message as it completes the dump of each volume. +

The message has the following format: +

   time_stamp: Task task_ID: total KB: volume: volume_total B
+

where +

time_stamp +: Records the time at which the message is printed, in the format +hours:minutes:seconds. +
task_ID +: Is the task identification number assigned to the operation by the Tape +Coordinator. The first digits in the number are the Tape +Coordinator's port offset number. +
total +: Is the total number of kilobytes transferred to the backup medium during +the current dump operation. +
volume +: Names the volume being dumped as the message is written. +
volume_total +: Is the total number of bytes dumped so far from the volume named in the +volume field. +

This instruction is intended for use with XBSA servers. For tape +devices and backup data files, the value in the volume_total field is +not necessarily as expected. It does not include certain kinds of +Backup System metadata (markers at the beginning and end of each volume, for +example), so summing together the final volume_total value for each +volume does not necessarily equal the running total in the total +field. Also, the Tape Coordinator does not write a message at all if it +is dumping metadata rather than actual volume data as it reaches the end of +the last buffer in each set of integer buffers. +

The TYPE Instruction +

The TYPE instruction takes a character string as its argument, +in the following format: +

   TYPE program_name   
+

where program_name names the XBSA server program that is running +on the machine named by the SERVER instruction. This +instruction is mandatory when the SERVER instruction appears in the +file. The acceptable values depend on which XBSA servers are supported +in the current AFS release. In the General Availability release of AFS +3.6, the only acceptable value is tsm. +

The UNMOUNT Instruction +

The UNMOUNT instruction takes a pathname as its argument, in the +following format: +

   UNMOUNT filename   
+

where filename is the full pathname of an executable file on the +local disk that contains a shell script or program (for clarity, the following +discussion refers to scripts only). If the configuration file is for an +automated tape device, the script invokes the routine or command provided by +the device's manufacturer for unmounting a tape (removing it from the +tape reader). If the configuration file is for a backup data file, it +can instruct the Tape Coordinator to perform additional actions after closing +the backup data file. This instruction does not apply to XBSA +servers. +

After closing a tape device or backup data file, 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 +

Examples +

Example CFG_tcid 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
+

   #! /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}   
+

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 the operation +being performed is not one of those explicitly mentioned in the file (such as +a restore operation). +

Example CFG_tcid 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 chooses to name the configuration file +/usr/afs/backup/CFG_20, using the port offset number rather than +deriving the tcid portion of the name from the backup data +file's name. She includes the following lines in the file. +To review the meaning of each instruction, see the preceding +Description section. +

   MOUNT /usr/afs/backup/file
+   FILE YES
+   ASK NO   
+

   #! /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}   
+

Example CFG_tcid File for an XBSA +Server +

The following is an example of a configuration file called +/usr/afs/backup/CFG_22, for a Tape Coordinator with port offset 22 +that communicates with an Tivoli Storage Management (TSM) server. The +combination of BUFFERSIZE and STATUS instructions +results in a status message after each 16 MB of data are dumped. To +review the meaning of the other instructions, see the preceding +Description section. +

   SERVER tsmserver1.abc.com
+   TYPE tsm
+   PASSWORD  TESTPASS
+   NODE testnode
+   MGMTCLASS standard
+   MAXPASS 1
+   GROUPID 1000
+   CENTRALLOG /usr/afs/backup/centrallog
+   BUFFERSIZE 16K
+   STATUS 1024
+

Related Information +

tapeconfig +

backup deletedump +

backup diskrestore +

backup dump +

backup dumpinfo +

backup restoredb +

backup savedb +

backup volrestore +

backup volsetrestore +

NetRestrict (client version)

Purpose +

Defines client interfaces not to register with the File Server +

Description +

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. +

To display the addresses the Cache Manager is currently registering with +File Servers, use the fs getclientaddrs command. +

Related Information +

NetInfo (client version) +

fs getclientaddrs +

NetRestrict (server version)

Purpose +

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 +

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. +

To display the File Server interface addresses registered in the VLDB, use +the vos listaddrs command. +

Related Information +

NetInfo (server version) +

sysid +

vldb.DB0 and vldb.DBSYS1 +

fileserver +

vos listaddrs +

backup deletedump

Purpose +

Deletes one or more dump records from the Backup Database +

Synopsis +

backup deletedump [-dumpid <dump id>⁺]  [-from <date time>⁺]  [-to <date time>⁺]
+                  [-port <TC port offset>]  [-groupid <group ID>]  
+                  [-dbonly]  [-force]  [-noexecute]
+                  [-localauth]  [-cell <cell name>]  [-help]
+  
+backup dele [-du <dump id>⁺]  [-fr <date time>⁺]  [-t <date time>⁺]
+            [-p <TC port offset>]  [-g <group ID>]  [-db]  [-fo]  [-n]  
+            [-l]  [-c <cell name>]  [-h]
+

Description +

The backup deletedump command deletes one or more dump records +from the Backup Database. Using this command is appropriate when dump +records are incorrect (possibly because a dump operation was interrupted or +failed), or when they represent dumps that are expired or otherwise no longer +needed. +

To specify the records to delete, use one of the following arguments or +combinations of arguments: +

The -dumpid argument deletes the record for each specified dump +ID number. +
The -groupid argument deletes each record with the specified +group ID number. A group ID number is associated with a record if the +GROUPID instruction appears in the Tape Coordinator's +/usr/afs/backup/CFG_tcid file when the dump is created. +To display a dump set's group ID, include the -verbose and +-id options to the backup dumpinfo command; the +group ID appears in the output's Group id field. +
The -from and -to arguments delete the records for +all regular dumps created during the time period bracketed by the specified +values. The -from argument can be omitted, in which case the +command deletes records created before the time specified by the +-to argument. +
The combination of the -groupid, -to and optionally +-from arguments deletes the records for all regular dumps created +during the specified time period that are also marked with the specified group +ID number. +

The command can also delete dump records maintained by an XBSA server at +the same time as the corresponding Backup Database records. (An +XBSA server is a third-party backup utility that implements the +Open Group's Backup Service API [XBSA].) Include the +-port argument to identify the Tape Coordinator that communicates +with the XBSA server. To delete the Backup Database records without +attempting to delete the records at the XBSA server, include the +-dbonly flag. To delete the Backup Database records even if +an attempt to delete the records at the XBSA server fails, include the +-force flag. +

Cautions +

The only way to remove the dump record for an appended dump is to remove +the record for its initial dump, and doing so removes the records for all +dumps appended to the initial dump. +

Removing a dump's record makes it impossible to restore data from it +or from any dump that refers to the deleted dump as its parent, directly or +indirectly. That is, restore operations must begin with a full dump and +continue with each incremental dump in order. If the records for a +specific dump are removed, it is not possible to restore data from later +incremental dumps. If necessary, use the -dbadd flag to the +backup scantape command to regenerate a dump record so that the +dump can act as a parent again. +

Options +

-dumpid +

Provide either this argument, the -to (and optionally +-from) argument, or the -groupid argument. +

-from +

Specifies the beginning of a range of dates; the record for any dump +created during the indicated period of time is deleted. +

-to +

Specifies the end of a range of dates; the record of any regular dump +created during the range is deleted from the Backup Database. +

Provide either this argument, the -dumpid argument, or the +-groupid argument, or combine this argument and the +-groupid argument. This argument is required if the +-from argument is provided. +

-port +

Specifies the port offset number of the Tape Coordinator that communicates +with the XBSA server that maintains the records to delete. It must be +the Tape Coordinator that transferred AFS data to the XBSA server when the +dump was created. The corresponding records in the Backup Database are +also deleted. +

This argument is meaningful only when deleting records maintained by an +XBSA server. Do not combine it with the -dbonly flag. +If this argument is omitted when other options pertinent to an XBSA server are +included, the Tape Coordinator with port offset 0 (zero) is used. +

-groupid +

Specifies the group ID number that is associated with the records to +delete. The Tape Coordinator ignores group IDs if this argument is +omitted. +

Provide either this argument, the -dumpid argument, or the +-to argument, or combine this argument and the -to +argument with any options other than the -dumpid argument. +

-dbonly +

Deletes records from the Backup Database without attempting to delete the +corresponding records maintained by an XBSA server. Do not combine this +flag with the -port argument or the -force flag. +

-force +

Deletes the specified records from the Backup Database even when the +attempt to delete the corresponding records maintained by an XBSA server +fails. Do not combine this flag with the -dbonly +flag. To identify the Tape Coordinator when this argument is used, +either provide the -port argument or omit it to specify the Tape +Coordinator with port offset 0 (zero). +

-noexecute +

Displays a list of the dump records to be deleted, without actually +deleting them. Combine it with the options to be included on the actual +command. +

-localauth +

-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 +

If the -noexecute flag is not included, the output generated at +the conclusion of processing lists the dump IDs of all deleted dump records, +in the following format: +

   The following dumps were deleted:
+        dump ID 1
+        dump ID 2
+        etc.   
+

If the -noexecute flag is included, the output instead lists the +dump IDs of all dump records to be deleted, in the following format: +

   The following dumps would have been deleted:
+        dump ID 1
+        dump ID 2
+        etc.   
+

The notation Appended Dump after a dump ID indicates that the +dump is to be deleted because it is appended to an initial dump that also +appears in the list, even if the appended dump's dump ID or group ID +number was not specified on the command line. For more about deleting +appended dumps, see the preceding Cautions section of this +reference page. +

Examples +

The following command deletes the dump record with dump ID 653777462, and +for any appended dumps associated with it: +

   % backup deletedump -dumpid 653777462
+   The following dumps were deleted:
+        653777462   
+

The following command deletes the Backup Database record of all dumps +created between midnight on 1 January 1999 and 23:59:59 hours on +31 December 1999: +

   % backup deletedump -from 01/01/1999 -to 12/31/1999
+   The following dumps were deleted:
+        598324045
+        598346873
+           ...
+           ...
+        653777523
+        653779648      
+

Privilege Required +

Related Information +

CFG_tcid +

backup +

backup dumpinfo +

backup scantape +

backup dumpinfo

Purpose +

Displays a dump record from the Backup Database +

Synopsis +

backup dumpinfo [-ndumps <no. of dumps>]  [-id <dump id>]
+                [-verbose]  [-localauth]  [-cell <cell name>]  [-help ]
+   
+backup dumpi [-n <no. of dumps>]  [-i <dump id>]
+             [-v]  [-l]  [-c <cell name>]  [-h]
+

Description +

The -verbose flag produces very detailed information that is +useful mostly for debugging purposes. It can be combined only with the +-id argument. +

Options +

-ndumps +: Displays the Backup Database record for each of the specified number of +dumps that were most recently performed. If the database contains fewer +dumps than are requested, the output includes the records for all existing +dumps. Do not combine this argument with the -id or +-verbose options; omit all options to display the records for +the last 10 dumps. +
-id +: Specifies the dump ID number of a single dump for which to display the +Backup Database record. Precede the dump id value with the +-id switch; otherwise, the command interpreter interprets it +as the value of the -ndumps argument. Combine this argument +with the -verbose flag if desired, but not with the +-ndumps argument; omit all options to display the records for +the last 10 dumps. +
-verbose +: Provides more detailed information about the dump specified with the +-id argument, which must be provided along with it. Do not +combine this flag with the -ndumps 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. +

Output +

If the -ndumps argument is provided, the output presents the +following information in table form, with a separate line for each dump: +

dumpid +

The dump ID number. +

parentid +

The dump ID number of the dump's parent dump. A value of +0 (zero) identifies a full dump. +

lv +

created +

The date and time at which the Backup System started the dump operation +that created the dump. +

nt +

nvols +

dump name +

The dump name in the form +

   volume_set_name.dump_level_name (initial_dump_ID)
+   
+

where volume_set_name is the name of the volume set, and +dump_level_name is the last element in the dump level pathname at +which the volume set was dumped. +

If the -id argument is provided alone, the first line of output +begins with the string Dump and reports information for the entire +dump in the following fields: +

id +: The dump ID number. +
level +: The depth in the dump hierarchy of the dump level used to create the +dump. A value of 0 (zero) identifies a full dump. A +value of 1 (one) or greater indicates an incremental dump made at +the specified level in the dump hierarchy. +
volumes +: The number of volumes for which the dump includes data. +
created +: The date and time at which the dump operation began. +

If an XBSA server was the backup medium for the dump (rather than a tape +device or backup data file), the following line appears next: +

   Backup Service: XBSA_program: Server: hostname
+

where XBSA_program is the name of the XBSA-compliant program and +hostname is the name of the machine on which the program runs. +

name +: The tape's permanent name if it has one, or its AFS tape name +otherwise, and its tape ID number in parentheses. +
nVolumes +: The number of volumes for which this tape includes dump data. +
created +: The date and time at which the Tape Coordinator began writing data to this +tape. +

Pos +: The relative position of each volume in this tape or file. On a +tape, the counter begins at position 2 (the tape label occupies position 1), +and increments by one for each volume. For volumes in a backup data +file, the position numbers start with 1 and do not usually increment only by +one, because each is the ordinal of the 16 KB offset in the file at which the +volume's data begins. The difference between the position numbers +therefore indicates how many 16 KB blocks each volume's data +occupies. For example, if the second volume is at position 5 and the +third volume in the list is at position 9, that means that the dump of the +second volume occupies 64 KB (four 16-KB blocks) of space in the file. +
Clone time +: For a backup or read-only volume, the time at which it was cloned from its +read/write source. For a Read/Write volume, it is the same as the dump +creation date reported on the first line of the output. +
Nbytes +: The number of bytes of data in the dump of the volume. +
Volume +: The volume name, complete with .backup or +.readonly extension if appropriate. +

If both the -id and -verbose options are provided, +the output is divided into several sections: +

The first section, headed by the underlined string Dump, +includes information about the entire dump. The fields labeled +id, level, created, and nVolumes +report the same values (though in a different order) as appear on the first +line of output when the -id argument is provided by itself. +Other fields of potential interest to the backup operator are: +
+
Group id +
The dump's group ID number, which is recorded in the +dump's Backup Database record if the GROUPID instruction +appears in the Tape Coordinator's +/usr/afs/backup/CFG_tcid file when the dump is created. +
maxTapes +
The number of tapes that contain the dump set to which this dump +belongs. +
Start Tape Seq +
The ordinal of the tape on which this dump begins in the set of tapes that +contain the dump set. +
+
For each tape that contains data from this dump, there follows a section +headed by the underlined string Tape. The fields labeled +name, written, and nVolumes report the same +values (though in a different order) as appear on the second and third lines +of output when the -id argument is provided by itself. Other +fields of potential interest to the backup operator are: +
+
expires +
The date and time when this tape can be recycled, because all dumps it +contains have expired. +
nMBytes Data and nBytes Data +
Summed together, these fields represent the total amount of dumped data +actually from volumes (as opposed to labels, filemarks, and other +markers). +
KBytes Tape Used +
The number of kilobytes of tape (or disk space, for a backup data file) +used to store the dump data. It is generally larger than the sum of the +values in the nMBytes Data and nBytes Data fields, +because it includes the space required for the label, file marks and other +markers, and because the Backup System writes data at 16 KB offsets, even if +the data in a given block doesn't fill the entire 16 KB. +
+
For each volume on a given tape, there follows a section headed by the +underlined string Volume. The fields labeled +name, position, clone, and nBytes +report the same values (though in a different order) as appear in the table +that lists the volumes in each tape when the -id argument is +provided by itself. Other fields of potential interest to the backup +operator are: +
+
id +
The volume ID. +
tape +
The name of the tape containing this volume data. +
+

Examples +

The following example displays information about the last five dumps: +

The following example displays a more detailed record for a single +dump. +

   % backup dumpinfo -id 922097346
+   Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
+   Tape: name monday.user.backup (922097346)
+   nVolumes 1, created 03/22/1999 05:09
+    Pos       Clone time   Nbytes Volume
+      1 03/22/1999 04:43 27787914 user.pat.backup   
+

   % backup dumpinfo -id 922097346 -verbose
+   Dump
+   ----
+   id = 922097346
+   Initial id = 0
+   Appended id = 922099568
+   parent = 0
+   level = 0
+   flags = 0x0
+   volumeSet = user
+   dump path = /monday1
+   name = user.monday1
+   created = Mon Mar 22 05:09:06 1999
+   nVolumes = 1
+   Group id  = 10
+   tapeServer =
+   format= user.monday1.%d
+   maxTapes = 1
+   Start Tape Seq = 1
+   name = pat
+   instance =
+   cell =
+   Tape
+   ----
+   tape name = monday.user.backup
+   AFS tape name = user.monday1.1
+   flags = 0x20
+   written = Mon Mar 22 05:09:06 1999
+   expires = NEVER
+   kBytes Tape Used = 121
+   nMBytes Data = 0
+   nBytes  Data = 19092
+   nFiles = 0
+   nVolumes = 1
+   seq = 1
+   tapeid = 0
+   useCount = 1
+   dump = 922097346
+   Volume
+   ------
+   name = user.pat.backup
+   flags = 0x18
+   id = 536871640
+   server =
+   partition = 0
+   nFrags = 1
+   position = 2
+   clone = Mon Mar 22 04:43:06 1999
+   startByte = 0
+   nBytes = 19092
+   seq = 0
+   dump = 922097346
+   tape = user.monday1.1   
+

Privilege Required +

Related Information +

backup +

backup deletedump +

backup status

Purpose +

Reports a Tape Coordinator's status +

Synopsis +

backup status [-portoffset <TC port offset>]
+              [-localauth]  [-cell <cell name>]  [-help]
+  
+backup st [-p <TC port offset>]  [-l]  [-c <cell name>]  [-h]
+

Description +

The backup status command displays which operation, if any, the +indicated Tape Coordinator is currently executing. +

Options +

-portoffset +: Specifies the port offset number of the Tape Coordinator for which to +report the status. +
-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 following message indicates that the Tape Coordinator is not currently +performing an operation: +

   Tape coordinator is idle
+

Otherwise, the output includes a message of the following format for each +running or pending operation: +

   Task task_ID:  operation:   status
+

where +

task_ID +

Is a task identification number assigned by the Tape Coordinator. +It begins with the Tape Coordinator's port offset number. +

operation +

Identifies the operation the Tape Coordinator is performing, which is +initiated by the indicated command: +

Dump (the backup dump command) +
Restore (the backup diskrestore, backup +volrestore, or backup volsetrestore commands) +
Labeltape (the backup labeltape command) +
Scantape (the backup scantape command) +
SaveDb (the backup savedb command) +
RestoreDb (the backup restoredb command) +

status +

Indicates the job's current status in one of the following +messages. +

number Kbytes transferred, volume volume_name +: For a running dump operation, indicates the number of kilobytes copied to +tape or a backup data file so far, and the volume currently being +dumped. +
number Kbytes, restore.volume +: For a running restore operation, indicates the number of kilobytes copied +into AFS from a tape or a backup data file so far. +
[abort requested] +: The (backup) kill command was issued, but the termination +signal has yet to reach the Tape Coordinator. +
[abort sent] +: The operation is canceled by the (backup) kill command. +Once the Backup System removes an operation from the queue or stops it from +running, it no longer appears at all in the output from the command. +
[butc contact lost] +: The backup command interpreter cannot reach the Tape +Coordinator. The message can mean either that the Tape Coordinator +handling the operation was terminated or failed while the operation was +running, or that the connection to the Tape Coordinator timed out. +
[done] +: The Tape Coordinator has finished the operation. +
[drive wait] +: The operation is waiting for the specified tape drive to become +free. +
[operator wait] +: The Tape Coordinator is waiting for the backup operator to insert a tape +in the drive. +

   XBSA_program Tape coordinator
+

where XBSA_program is the name of the XBSA-compliant +program. +

Examples +

   % backup status -portoffset 4
+   Task 4001:  Dump:   1520 Kbytes transferred,  volume user.pat.backup   
+

Privilege Required +

Related Information +

backup +

butc +

vos delentry

Purpose +

Removes a volume entry from the VLDB. +

Synopsis +

vos delentry [-id <volume name or ID>⁺]
+             [-prefix <prefix of volume whose VLDB entry is to be deleted>] 
+             [-server <machine name>]  [-partition <partition name>]  
+             [-cell <cell name>]  [-noauth]  [-localauth]  [-verbose]  [-help]
+     
+vos de [-i <volume name or ID>⁺]
+       [-pr <prefix of volume whose VLDB entry is to be deleted>]  
+       [-s <machine name>]  [-pa <partition name>]  [-c <cell name>] 
+       [-n]  [-l]  [-v]  [-h]
+

Description +

The vos delentry command removes the Volume Location Database +(VLDB) entry for each specified volume. Specify one or more read/write +volumes; specifying a read-only or backup volume results in an +error. The command has no effect on the actual volumes on file server +machines, if they exist. +

For every volume whose name begins with a certain character string (for +example, sys. or user.): use the +-prefix argument. +
Every volume for which the VLDB lists a site on a certain file server +machine: specify the file server name with the -server +argument. +
Every volume for which the VLDB lists a site on a partition of the same +name (for instance, on the /vicepa partition on any file server +machine): specify the partition name with the -partition +argument. +
Every volume for which the VLDB lists a site one a specific partition of a +file server machine: specify both the -server and +-partition arguments. +
Every volume whose name begins with a certain prefix and for which the +VLDB lists a site on a file server machine: combine the +-prefix and -server arguments. Combine the +-prefix argument with the -partition argument, or both +the -server and -partition arguments, to remove a more +specific group of volumes. +

Cautions +

A single VLDB entry represents all versions of a volume (read/write, +readonly, and backup). The command removes the entire entry even though +only the read/write volume is specified. +

Options +

-id +

Specifies the complete name or volume ID number of each read/write volume +for which to remove the VLDB entry. The entire entry is removed. +Provide this argument or some combination of the -prefix, +-server, and -partition arguments. +

-prefix +

-server +

Combine this argument with the -prefix argument, the +-partition argument, or both. +

-partition +

Combine this argument with the -prefix argument, the +-server argument, or both. +

-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 vos reference page. +

-noauth +

Assigns the unprivileged identity anonymous to the +issuer. Do not combine this flag with the -localauth +flag. For more details, see the introductory vos reference +page. +

-localauth +

-verbose +

Produces on the standard output stream a detailed trace of the +command's execution. If this argument is omitted, only warnings +and error messages appear. +

-help +

Prints the online help for this command. All other valid options +are ignored. +

Output +

The following message confirms the success of the command by indicating how +many VLDB entries were removed. +

   Deleted number VLDB entries   
+

Examples +

The following command removes the VLDB entry for the volume +user.temp. +

   % vos delentry user.temp   
+

The following command removes the VLDB entry for every volume whose name +begins with the string test and for which the VLDB lists a site on +the file server machine fs3.abc.com. +

   % vos delentry -prefix test -server fs3.abc.com   
+

Privilege Required +

Related Information +

vos +

vos remove +

vos syncserv +

vos syncvldb +

vos zap +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/UserGuide/auusg000.htm b/doc/html/UserGuide/auusg000.htm new file mode 100644 index 0000000..42c7d70 --- /dev/null +++ b/doc/html/UserGuide/auusg000.htm @@ -0,0 +1,48 @@ + + +User Guide + + + + + + + + + + + +

User Guide

+AFS
+User Guide
+

Version 3.6 +

Document Number GC09-4561-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 +

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. +

+ +

+
© IBM Corporation 2000. All Rights Reserved + + + + diff --git a/doc/html/UserGuide/auusg002.htm b/doc/html/UserGuide/auusg002.htm new file mode 100644 index 0000000..81afe40 --- /dev/null +++ b/doc/html/UserGuide/auusg002.htm @@ -0,0 +1,281 @@ + + +User Guide + + + + + + + + + + + +

User Guide

About This Guide
+

How To Use This Document +

Document Organization +