OpenAFS Administration Guide
   Next

OpenAFS Administration Guide

Copyright © 2000 IBM Corporation. All Rights Reserved

Revision History
Revision BP--1.6.x-4781-gc0876-dirty
Revision 3.6April 2000
First IBM Edition, Document Number GC09-4563-00

Abstract

This document describes the configuration and maintenance of OpenAFS from an adminstrator's standpoint. It provides a conceptual overview of OpenAFS for cell administrators, details on OpenAFS configuration, and information about managing OpenAFS servers and clients.

Table of Contents

About This Guide
Audience and Purpose
Document Organization
How to Use This Document
Related Documents
Typographical Conventions
I. Concepts and Configuration Issues
1. An Overview of OpenAFS Administration
A Broad Overview of AFS
AFS: A Distributed File System
Servers and Clients
Cells
Transparent Access and the Uniform Namespace
Volumes
Efficiency Boosters: Replication and Caching
Security: Mutual Authentication and Access Control Lists
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 Protection Server
The Volume Server
The Volume Location (VL) Server
The Salvager
The Update Server
The Backup Server
The Cache Manager
The Kerberos KDC
The Network Time Protocol Daemon
2. 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 and inode-based fileservers
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
Grouping Related Volumes on a Partition
When to Replicate Volumes
The Default Quota and ACL on a New Volume
Configuring Server Machines
Replicating the OpenAFS 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
Login and Authentication in AFS
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
Accessing AFS through NFS
II. Managing File Server Machines
3. Administering Server Machines
Summary of Instructions
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 OpenAFS 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
4. Monitoring and Controlling Server Processes
Summary of Instructions
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 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
5. Managing Volumes
Summary of Instructions
About Volumes
The Three Types of 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
To access volumes directly by volume ID
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
6. Configuring the AFS Backup System
Summary of Instructions
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
7. Backing Up and Restoring AFS Data
Summary of Instructions
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
8. Monitoring and Auditing AFS Performance
Summary of Instructions
Using the scout Program
System Requirements
Using the -basename argument to Specify a Domain Name
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
9. Managing Server Encryption Keys
Summary of Instructions
About Server Encryption Keys
Keys and Mutual Authentication: A Review
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
III. Managing Client Machines
10. Administering Client Machines and the Cache Manager
Summary of Instructions
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
Tuning 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
IV. Managing Users and Groups
11. Creating and Deleting User Accounts with the uss Command Suite
Summary of Instructions
Overview of the uss Command Suite
The Components of an AFS User Account
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
12. Administering User Accounts
Summary of Instructions
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
13. Administering the Protection Database
Summary of Instructions
About the Protection Database
The System Groups
Displaying Information from the Protection Database
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
14. Managing Access Control Lists
Summary of Instructions
Protecting Data in AFS
Differences Between UFS and AFS Data Protection
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
15. Managing Administrative Privilege
Summary of Instructions
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
A. Managing the NFS/AFS Translator
Summary of Instructions
Overview
Enabling Unauthenticated or Authenticated AFS Access
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
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
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)
CallBack Statistics Section (CallBackStats_section)
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

List of Figures

1. File Sharing Between the Read/write Source and a Clone Volume
2. First example scout display
3. Second example scout display
4. Third example scout display
5. Fourth example scout display
6. The afsmonitor System Overview Screen
7. The afsmonitor File Servers Screen
8. The afsmonitor File Servers Screen Shifted One Page to the Right
9. The afsmonitor Cache Managers Screen

List of Tables

1. Suggested volume prefixes
2. Example volume-prefixing scheme
3. Source for values of uss template variables
4. Command-line argument sources for uss template variables
   Next
   About This Guide