openafs-1.1.1a/doc/ 0042775 0000145 0001752 00000000000 07341113761 013420 5 ustar shadow htdocs openafs-1.1.1a/doc/html/ 0042775 0000145 0001752 00000000000 07341113761 014364 5 ustar shadow htdocs openafs-1.1.1a/doc/html/index.htm 0100664 0000145 0001752 00000003455 07321243715 016210 0 ustar shadow htdocs
Version 1.0
Document Number 0000-0000-00
First Edition (July 2001)
Included:
Version 3.6
Document Number GC09-4563-00
First Edition (April 2000)
This edition applies to:
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.
An Overview of AFS Administration
Issues in Cell Configuration and Administration
Monitoring and Controlling Server Processes
Configuring the AFS Backup System
Backing Up and Restoring AFS Data
Monitoring and Auditing AFS Performance
Managing Server Encryption Keys
Administering Client Machines and the Cache Manager
Configuring Client Machines with the package Program
Creating and Deleting User Accounts with the uss Command Suite
Administering the Protection Database
Managing Administrative Privilege
Appendix A. Managing the NFS/AFS Translator
Appendix B. Using AFS Commands
Appendix C. The afsmonitor Program Statistics
This section describes the purpose, organization, and conventions of this document.
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.
This document groups AFS administrative tasks into the following conceptual sections:
The individual chapters in each section contain the following:
When you need to perform a specific administrative task, follow these steps:
The following documents are also included in the AFS documentation set.
IBM AFS Administration Reference
This reference manual details the syntax and effect of each AFS command. It is intended for the experienced AFS administrator, programmer, or user.
The IBM AFS Administration Reference lists AFS files and commands in alphabetical order. The reference page for each command specifies its syntax, including the acceptable aliases and abbreviations. It then describes the command's function, arguments, and output if any. Examples and a list of related commands are provided, as are warnings where appropriate.
This manual complements the IBM AFS Administration Guide: it does not include procedural information, but describes commands in more detail than the IBM AFS Administration Guide.
IBM AFS Quick Beginnings
This guide provides instructions for installing AFS server and client machines. It is assumed that the installer is an experienced UNIX (R) system administrator.
For predictable performance, machines must be installed and configured in accordance with the instructions in this guide.
IBM AFS Release Notes
This document provides information specific to each release of AFS, such as a list of new features and commands, a list of requirements and limitations, and instructions for upgrading server and client machines.
IBM AFS User Guide
This guide presents the basic concepts and procedures necessary for using AFS effectively. It assumes that the reader has some experience with UNIX, but does not require familiarity with networking or AFS.
The guide explains how to perform basic functions, including authenticating, changing a password, protecting AFS data, creating groups, and troubleshooting. It provides illustrative examples for each function and describes some of the differences between the UNIX file system and AFS.
This document uses the following typographical conventions:
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.
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.
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.
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.
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.
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 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.
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.
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 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.
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.
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.
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.
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 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 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.
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:
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:
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.
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 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:
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
The Authentication Server performs two main functions related to network security:
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 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:
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 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 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 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 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 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 (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.
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.
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.
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.
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 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.
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.
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.
This section summarizes how AFS modifies the functionality of some UNIX commands.
The AFS distribution for some system types possibly does not include a modified rlogind program. See the IBM AFS Release Notes.
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.
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.
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.
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.
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:
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.
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. |
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 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.
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.
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:
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.
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.
To make a foreign cell's filespace visible on a client machine in your cell, perform the following three steps:
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.
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:
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 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 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'
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:
As an example, files that other cells expect to find in this directory's etc subdirectory can include the following:
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
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.
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.
You can name your volumes anything you choose, subject to a few restrictions:
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 |
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 |
There are several advantages to this scheme:
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:
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
This section summarizes issues to consider as you install and configure client machines in your cell.
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.
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.
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.
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.
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.
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.
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
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:
For further discussion, see Converting Existing UNIX Accounts with uss or Converting Existing UNIX Accounts.
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.
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:
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.
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.
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.
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.
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:
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.
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.
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:
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.
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.
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:
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. |
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:
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.
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:
AFS(R) version Login
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:
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.
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:
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.
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--
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.
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. |
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.
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.
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.
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.
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:
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.
AFS uses three separate types of privilege for the reasons discussed in The Reason for Separate Privileges.
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.
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
Server Machines
System Administrators
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 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 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:
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:
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:
(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.)
AFS provides two related facilities that help the administrator back up AFS data: backup volumes and the AFS Backup System.
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.
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.
The AFS distribution includes modified versions of several standard UNIX commands, daemons and programs that provide remote services, including the following:
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.
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.
This chapter describes how to administer an AFS server machine. It describes the following configuration information and administrative tasks:
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.
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 |
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.
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.
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:
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:
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.
For instructions on maintaining this file, see Managing Server Encryption Keys.
Note that changing this file is only one step in changing your cell's name. For discussion, see Choosing a Cell Name.
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:
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.
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.
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.
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):
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.
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:
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. |
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:
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. |
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.
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.
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:
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:
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.
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.
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 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.
% 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.
% 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.
% 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.
% 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 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'
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)
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'
This section explains how to administer database server machines. For installation instructions, see the IBM AFS Quick Beginnings.
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.
This section describes how to configure your cell to maintain proper Ubik operation.
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.
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.)
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.
The following Ubik features help keep its maintenance requirements to a minimum:
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.
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.
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.
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.
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.
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.
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:
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.
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]
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:
# bos start <machine name> -instance <server process name>+ -localauth
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]
# 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
# cd /usr/afs/db # tar xvf tape_device database_file
where database_file is one of the following:
# bos start <machine name> -instance <server process name>+ -localauth
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.
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.
% bos listusers <machine name>
% bos install <machine name> <files to install>+
where
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.
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>+
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.
% bos listusers <machine name>
% bos uninstall <machine name> <files to uninstall>+
where
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>+
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.
% bos getdate <machine name> <files to check>+
where
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:
% bos listusers <machine name>
% bos prune <machine name> [-bak] [-old] [-core] [-all]
where
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.
% which binary_file /bin_dir_path/binary_file % cd bin_dir_path
% 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
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:
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 consequences of missing or incorrect information in the CellServDB file are as follows:
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.
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.
% bos listhosts <machine name> [<cell name>]
where
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.
% bos listusers <machine name>
% bos addhost <machine name> <host name>+
where
Important: Repeat the following command in quick succession on all of the database server machines.
% bos restart <machine name> buserver kaserver ptserver vlserver
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.
% bos listusers <machine name>
% bos removehost <machine name> <host name>+
where
Important: Repeat the following command in quick succession on all of the database server machines.
% bos restart <machine name> buserver kaserver ptserver vlserver
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.
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.
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:
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.
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. |
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.
% bos listusers <machine name>
% bos setauth <machine name> off
where
% bos setauth <machine name> on
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.
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.
This is not possible, except by issuing the unlog command to discard your tokens before issuing the fs command.
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 &
% su root Password: root_password
# vos listpart <machine name> -localauth
where
# mkdir /vicepx[x]
# bos shutdown <machine name> -localauth [-wait]
# bos restart <machine name> fs -localauth
# bos status <machine name>
% bos listusers <machine name>
% vos listvol <machine name> [<partition name>]
% vos move <volume name or ID> \ <machine name on source> <partition name on source> \ <machine name on destination> <partition name on destination>
% su root Password: root_password
# cd / # umount /dev/<partition_block_device_name>
# rmdir /vicepxx
# bos shutdown <machine name> -localauth [-wait]
# bos restart <machine name> fs -localauth
# bos status <machine name>
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.
% su root Password: root_password
% su root Password: root_password
% 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.
% bos listusers <machine name>
% vos changeaddr <original IP address> -remove
where
% bos listusers <machine name>
% bos shutdown <machine name>
% 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.
% bos restart <machine name> fs
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 &
% su root Password: root_password
# bos shutdown <machine name> -localauth [-wait]
# shutdown
% bos listusers <machine name>
% bos shutdown <machine name> [-wait]
% bos exec <machine name> reboot_command
where
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.
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 |
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 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, 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.
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 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.
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.
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
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, 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.
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.
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 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:
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.
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, 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).
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.
A process's entry in the BosConfig file includes the following information:
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.
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.
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.
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.
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.
% bos status <machine name> [<server process name>+] [-long]
where
The output includes an entry for each process and uses one of the following strings to indicate the process's status:
The output for the fs process always includes a message marked Auxiliary status, which can be one of the following:
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:
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'
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. |
% bos listusers <machine name>
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
% bos create <machine name> <server process name> \ <server type> <command lines>+ [ -notifier <Notifier program>]
where
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 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
% bos listusers <machine name>
% bos stop <machine name> <server process name>+ [-wait]
% bos delete <machine name> <server process name>+
where
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.
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. |
% bos listusers <machine name>
% bos stop <machine name> <server process name>+ [-wait]
where
% bos listusers <machine name>
% bos start <machine name> <server process name>+
where
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. |
% bos listusers <machine name>
% bos shutdown <machine name> [<instances>+] [-wait]
where
% bos listusers <machine name>
% bos startup <machine name>
where
% bos listusers <machine name>
% bos startup <machine name> <instances>+
where
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:
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.
% bos listusers <machine name>
% bos restart <machine name> -bosserver
where
% bos listusers <machine name>
% bos restart <machine name> -all
where
% bos listusers <machine name>
% bos restart <machine name> <instances>+
where
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.
% bos getrestart <machine name>
where
% bos listusers <machine name>
% bos setrestart <machine name> "<time to restart server>" [-general] [-newbinary]
where
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). |
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. |
% bos listusers <machine name>
% bos getlog <machine name> <log file to examine>
where
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.
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.
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 |
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.
There are three types of volumes in AFS, as described in the following list:
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.
Volumes make your cell easier to manage and more efficient in the following three ways:
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.
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.)
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.
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.
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.
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.
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:
To change the quota after creation, use the fs setquota command as described in Setting and Displaying Volume Quota and Current Size.
% bos listusers <machine name>
% 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.
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
% vos create <machine name> <partition name> <volume name> \ [-maxquota <initial quota (KB)>]
where
% fs mkmount <directory> <volume name>
% fs lsmount <directory>
% fs setvol <dir/file path> -offlinemsg <offline message>
where
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.
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:
Figure 1. File Sharing Between the Read/write Source and a Clone Volume
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:
By default, the Volume Server determines automatically whether or not it needs to create a new ReleaseClone:
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.
For maximum effectiveness, replicate only volumes that satisfy two criteria:
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.
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:
% bos listusers <machine name>
% vos examine <volume name or ID>
The final lines of output display the volume's site definitions from the VLDB.
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>]
% vos addsite <machine name> <partition name> <volume name or ID>
where
% bos status <machine name> fs vlserver
% vos release <volume name or ID> [-f]
where
% 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.
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:
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:
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:
-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.
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"
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.
% bos listusers <machine name>
% 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.
% vos backup <volume name or ID> Created backup volume for volume name or ID
where
% fs mkmount <directory> <volume name>.backup
where
% fs lsmount <directory>
% bos listusers <machine name>
% vos backupsys [-prefix <common prefix on volume(s)>+] \ [-server <machine name>] [-partition <partition name>] \ [-exclude] [-xprefix <negative prefix on volume(s)>+] [-dryrun] [-verbose]
where
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 Cache Manager observes three basic rules as it traverses the AFS filespace and encounters mount points:
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.
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.
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.
AFS uses three types of mount points, each appropriate for a different purpose because of how the Cache Manager handles them.
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. |
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.
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'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.
% fs lsmount <directory>
where
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.
% fs listacl [<dir/file path>]
% fs mkmount <directory> <volume name> [-rw]
where
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.
% fs listacl [<dir/file path>]
Substitute your cell's name for cellname.
% cd /afs/.cellname % fs mkmount new_cells root.afs % cd new_cells
% fs mkmount <directory> <volume name> -cell <cell name>
where
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.
% 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.
% fs rmmount <directory>
where
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.
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.
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:
% vos listvldb [-name <volume name or ID>] [-server <machine name>] \ [-partition <partition name>] [-locked]
where
The VLDB entry for each volume includes the following information:
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
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.
% vos listvol <machine name> [<partition name>] [-fast] [-long] [-extended]
where
The output is ordered alphabetically by volume name and by default provides the following information on a single line for each volume:
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
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:
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:
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 | |-------------------------------------------|
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.
% vos examine <volume name or ID>
where
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
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:
You can also use the command to learn a volume's name by providing its ID number.
% fs listquota [<dir/file path>]
where
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%
% fs examine [<dir/file path>]
where
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: | 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. |
% fs whereis [<dir/file path>]
where
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
% 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>
There are three main reasons to move volumes:
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.
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.
% bos listusers <machine name>
% vos move <volume name or ID> \ <machine name on source> <partition name on source > \ <machine name on destination> <partition name on destination>
where
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. |
% vos listvldb <volume name or ID>
% vos backup <volume name or ID>
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.
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:
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.
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.
% bos listusers <machine name>
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
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
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.
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.
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.
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:
Combine the bos salvage command's arguments as indicated to salvage different numbers of volumes:
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
% bos listusers <machine name>
% 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
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.
_ _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.
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.
% pts membership system:administrators
% fs setquota [<dir/file path>] -max <max quota in kbytes>
where
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.
% pts membership system:administrators
% fs setvol [<dir/file path>+] -max <disk space quota in 1K units>
where
% fs quota [<dir/file path>+]
where
The following example illustrates the output produced by this command:
% fs quota /afs/abc.com/usr/terry 34% of quota used.
% fs listquota [<dir/file path>+]
where
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%
% fs examine [<dir/file path>+]
where
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: | 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. |
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 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 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.
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.
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.
% bos listusers <machine name>
% 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.
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.
% vos remove [-server machine name>] [-partition <partition name>] \ -id <volume name or ID>
where
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>
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.
Dumping a volume can be useful in several situations, including the following:
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.
% bos listusers <machine name>
% 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.
% vos dump -id <volume name or ID> [-time <dump from time>] [-file <arg>] [-server <server>] [-partition <partition>]
where
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.
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 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.
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.
% bos listusers <machine name>
% 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.
% vos partinfo <machine name> [<partition name>]
% vos restore <machine name> <partition name> \ <name of volume to be restored> \ [-file <dump file>] [-id <volume ID>]
where
% fs mkmount <directory> <volume name>
% fs lsmount <directory>
% bos listusers <machine name>
% 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.
% vos restore <machine name> <partition name> \ <name of volume to be restored> \ [-file <dump file>] \ -overwrite <full | incremental>
where
% vos release <volume name or ID>
% vos backup <volume name or ID>
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.
% bos listusers <machine name>
% 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.
% vos rename <old volume name> <new volume name>
where
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.
% fs rmmount <directory>
% fs mkmount <directory> <volume name> [-rw]
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.
% bos listusers <machine name>
% vos lock <volume name or ID>
where
% bos listusers <machine name>
% vos unlock <volume name or ID>
where
% bos listusers <machine name>
% vos unlockvldb [<machine name>] [<partition name>]
where
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.
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 |
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.
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.
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.
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.
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.
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:
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.
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 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.
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 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 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:
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.
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:
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.
Several factors interact to determine how much data the Tape Coordinator can fit on a tape:
(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
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.
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.
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.
% fms <tape special file>
where
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
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:
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.
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. |
% bos listusers <machine name>
% su root Password: root_password
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).
# ls /usr/afsws/etc
# mkdir /usr/afs # mkdir /usr/afs/backup
# 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
# backup addhost <tape machine name> [<TC port offset>]
where
% bos listusers <machine name>
% su root Password: root_password
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'
# backup listhosts
where listh is the shortest acceptable abbreviation of listhosts.
# backup addhost <tape machine name> [<TC port offset>]
% bos listusers <machine name>
% backup delhost <tape machine name> [<TC port offset>]
where
% backup listhosts
where
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
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:
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:
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:
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.
% bos listusers <machine name>
% backup
backup> addvolset <volume set name> [-temporary]
where
% bos listusers <machine name>
% backup
backup> addvolentry -name <volume set name> \ -server <machine name> \ -partition <partition name> \ -volumes <volume name (regular expression)>
where
% backup listvolsets [<volume set name>]
where
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\..*
% bos listusers <machine name>
% backup delvolset <volume set name>+
where
% bos listusers <machine name>
% backup
backup> listvolsets <volume set name>
where
backup> delvolentry <volume set name> <volume entry index>
where
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:
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).
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.
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.
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).
[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.
[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.
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.
% bos listusers <machine name>
% backup
backup> adddump -dump <dump level name>+ [-expires <expiration date>+]
where
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.
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. |
% bos listusers <machine name>
% backup
backup> setexp -dump <dump level name>+ [-expires <expiration date>+]
where
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. |
% bos listusers <machine name>
% backup
backup> deldump <dump level name>
where
% 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
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:
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. |
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 ""
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.
% bos listusers <machine name>
% butc [<port offset>] [-noautoquery]
% backup
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
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).
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.
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.
% bos listusers <machine name>
% butc [<port offset>] [-noautoquery]
% backup
backup> readlabel [<TC port offset>]
where
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 --
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.
There are two additional ways to increase backup automation and efficiency that do not involve the 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.
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.
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.
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.
Your MOUNT script must return one of the following exit codes to tell the Tape Coordinator whether or not it mounted the tape successfully:
When the Tape Coordinator executes the UNMOUNT script, it passes in two parameters in the following order.
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}
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:
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.
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.
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:
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.)
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.
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. |
% bos listusers <machine name>
% su root Password: root_password
# backup
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.
backup> addhost <tape machine name> [<TC port offset>]
where
[capacity filemark_size] device_name port_offset
where
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.
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.
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.
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}
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.
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 |
When performing backup operations, you interact with three Backup System components:
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.
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.
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.
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.
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:
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.
% bos listusers <machine name>
% backup backup>
backup> quit %
backup> jobs
where
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
The line for a pending or running operation of any other type has the following format:
Job job_ID: operation status
where
volume_set_name.dump_level_name
backup> jobs
backup> kill <job ID or dump set name>
where
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.
% bos listusers <machine name>
Alternately, you can log into a file server machine as the local superuser root in Step 3.
If you plan to include the -localauth flag to the butc command in the next step, log in as the local superuser root.
% butc [<port offset>] [-debuglevel <trace level>] \ [-cell <cellname>] [-noautoquery] [-localauth]
where
% bos listusers <machine name>
% backup status [<TC port offset>]
where
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
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.
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:
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:
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.
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.
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.)
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
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.
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.
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.
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:
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 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.
If it is set to NO or does not appear in the file, the Tape Coordinator writes to a tape device.
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.
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.
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).
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.
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)
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.
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:
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.
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:
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:
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.
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:
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.
% bos listusers <machine name>
% butc [<port offset>] [-noautoquery]
% backup
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)>
backup> dump <volume set name> <dump level name> [<TC port offset>] \ [-at <Date/time to start dump>+] \ [-append] [-n] [-file <load file>]
where
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. |
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 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.
It is also a good idea to record the tape name and dump ID number on the exterior label of each tape.
The backup command suite includes three commands for displaying information about data you have backed up:
% bos listusers <machine name>
% backup dumpinfo [-ndumps <no. of dumps>] [-id <dump id>] [-verbose]
where
If the -ndumps argument is provided, the output presents the following information in table form, with a separate line for each dump:
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:
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:
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:
If both the -id and -verbose options are provided, the output is divided into several sections:
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
% bos listusers <machine name>
% backup volinfo <volume name>
where
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:
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 . . . . . . . . . . . . . . . .
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:
|
% bos listusers <machine name>
% butc [<port offset>] [-noautoquery]
% backup
backup> scantape [-dbadd] [-portoffset <TC port offset>]
where
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
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:
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.
The following comments apply to all types of restore operation:
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.
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:
% bos listusers <machine name>
% butc [<port offset>] [-noautoquery]
Repeat the command for each Tape Coordinator if you are using more than one tape device.
% backup
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
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. |
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.
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.
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.
% bos listusers <machine name>
% butc [<port offset>] [-noautoquery]
Repeat the command for each Tape Coordinator if you are using more than one tape device.
% backup
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
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.
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.
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.
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.
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
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
To make the entries suitable for use with the -file argument, edit them as indicated:
% bos listusers <machine name>
% butc [<port offset>] [-noautoquery]
Repeat the command for each Tape Coordinator if you are using more than one tape device.
% backup
backup> addvolset <volume set name> [-temporary] backup> addvolentry -name <volume set name> \ -server <machine name> \ -partition <partition name> \ -volumes <volume name (regular expression)>
backup> volsetrestore [-name <volume set name>] \ [-file <file name>] \ [-portoffset <TC port offset>+] \ [-extension <new volume name extension>] [-n]
where
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.
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.
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.
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.
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.
% bos listusers <machine name>
% backup dbverify [-detail]
where
The output reports one of the following messages:
% butc [<port offset>] [-noautoquery]
# 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.
backup> status -portoffset <TC port offset>
backup> savedb [-portoffset <TC port offset>]
where
backup> quit
# /usr/afs/bin/bos shutdown <machine name> buserver -localauth -wait
# cd /usr/afs/db # rm bdb.DB0 # rm bdb.DBSYS1
# /usr/afs/bin/bos start <machine name> buserver -localauth
# backup -localauth
where -localauth constructs a server ticket from the local /usr/afs/etc/KeyFile file.
backup> addhost <tape machine name> [<TC port offset>]
backup> restoredb [-portoffset <TC port offset>]
where
backup> quit
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.
% bos listusers <machine name>
% backup
backup> dumpinfo [<no. of dumps>] [-id <dump id>] [-verbose]
backup> deletedump [-dumpid <dumpid>+] [-from <date time>] \ [-to <date time>]
where
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 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. |
AFS comes with three main monitoring tools:
AFS also provides a tool for auditing AFS events on file server machines running AIX.
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 |
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.
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.
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:
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.
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:
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
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 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.
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 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.
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.
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.
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.
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
% 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
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.)
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
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.
% 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
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 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:
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. |
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.
To use fstrace commands most effectively, configure them as indicated:
To start Cache Manager tracing on an AFS client machine, you must first configure
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.
% su root Password: root_password
# 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
% su root Password: root_password
% fstrace setset [-set <set_name>+] [-active] [-inactive] \ [-dormant]
The following example activates the cm event set.
# fstrace setset cm -active
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.
% su root Password: root_password
# 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:
% su root Password: root_password
# 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:
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.)
% su root Password: root_password
# 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:
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:
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. |
% su root Password: root_password
# 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
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
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.
The following software must be accessible to a machine where the afsmonitor program is running:
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 program displays its data on three screens:
Fields at the corners of every screen display the following information:
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.
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:
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 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 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
|
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 following list describes the instructions that can appear in the configuration file:
The parameters fs, cm, field_name, threshold_val, and arg1 through argn correspond to the values with the same name on the thresh line. The host_name parameter identifies the file server or client machine where the statistic has crossed the threshold, and the actual_val parameter is the actual value of field_name that 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.
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.
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:
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).
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:
% 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
To exit an afsmonitor program session, Enter the <Ctrl-c> interrupt signal or an uppercase Q.
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:
The libraries allow the caller to register
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_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:
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.
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.
% 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
There are two acceptable values:
% 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
There are two acceptable values:
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.
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. |
The directory /usr/afs/local/audit contains three files that contain the information needed to configure AIX File Servers to audit AFS events:
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.
AFS_AUDIT_AllEvents
This chapter explains how to maintain your cell's server encryption keys, which are vital for secure communications in AFS.
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 |
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.
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.
As you maintain your cell's server encryption keys, keep the following in mind.
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.
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.
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.
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.
% bos listusers <machine name>
% bos listkeys <machine name> [-showkey]
where
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.
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
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
As noted, AFS records server encryption keys in two separate places:
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.
% bos listusers <machine name>
% bos listkeys <machine name>
where
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
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.
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.
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.
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
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
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.
% bos listusers <machine name>
% bos listkeys <machine name>
% kas examine afs -admin <admin principal to use for authentication> Administrator's (admin_user) password: admin_password
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
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.
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.
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.
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.
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.
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.
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.
% su root Password: root_password
# touch /usr/afs/local/NoAuth
# unlog
% su root Password: root_password
# rm /usr/afs/local/NoAuth
# klog <admin_user> Password: <admin_password>
# bos listkeys <machine name> -noauth
where
# bos addkey <machine name> -kvno <key version number> -noauth input key: afs_password Retype input key: afs_password
where
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.
# 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.
# kas setpassword -name afs -kvno <key version number> -noauth new_password: afs_password Verifying, please re-enter new_password: afs_password
where
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:
To learn how to install the client functionality on a machine, see the IBM AFS Quick Beginnings.
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 |
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.
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.
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.
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.
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.
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.
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).
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:
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.
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.
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.
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.
% cat /usr/vice/etc/cacheinfo
% 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.
% su root Password: root_password
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
% su root Password: root_password
Note: | This command does not work for a memory cache. |
# fs setcachesize <size in 1K byte blocks (0 => reset)>
where
% su root Password: root_password
# fs setcachesize 0
# fs setcachesize -reset
where
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:
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.
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.
The cache configuration parameters with the most direct effect on cache performance include the following:
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.
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.
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.
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:
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 (210 = 1024); a value of 16 equals the default for disk caches (216 = 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 (214):
/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.
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:
/usr/vice/etc/afsd -memcache -blocks 5120
/usr/vice/etc/afsd -memcache -chunksize 12
/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.
Do not use the following arguments for a memory cache:
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:
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.)
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:
The consequences of missing or incorrect information in the CellServDB file or kernel memory are as follows:
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
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. |
% cat /usr/vice/etc/CellServDB
% 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 . .
% su root Password: root_password
# fs listacl [<dir/file path>]
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
# /etc/package -v -c <name of package file>
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.
% fs getcellstatus <cell name>
where
The output reports the setuid status of each cell:
% su root Password: root_password
# fs setcell <cell name>+ [-suid] [-nosuid]
where
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.
% su root Password: root_password
# fs checkservers -interval <seconds between probes>
where
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:
% cat /usr/vice/etc/ThisCell
% su root Password: root_password
# sync # shutdown
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:
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.
% fs flush [<dir/file path>+]
where
% fs flushvolume [<dir/file path>+]
where
% 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.
% fs flush [<dir/file path>+]
where
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.
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 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.
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.
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:
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.
% fs getserverprefs [-file <output to named file>] [-numeric] [-vlservers]
where
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 . . . . . . .
% su root Password: root_password
# fs setserverprefs [-servers <fileserver names and ranks>+] \ [-vlservers <VL server names and ranks>+] \ [-file <input from named file>] [-stdin]
where
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:
(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:
% su root Password: root_password
% su root Password: root_password
% 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.
% su root Password: root_password
# fs setclientaddrs [-address <client network interfaces>+]
where
By default, the Cache Manager generates two types of warning and informational messages:
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.
% su root Password: root_password
# fs messages -show <user|console|all|none>
where
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.
% 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.
% su root Password: root_password
# fs sysname <new sysname>
where
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:
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:
% su root Password: root_password
# fs storebehind -allfiles <new default (KB)> [-verbose]
where
% 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
# fs storebehind -kbytes <asynchrony for specified names> \ -files <specific pathnames>+ \ [-verbose]
where
% fs storebehind [-verbose]
where
% fs storebehind -files <specific pathnames>+
where
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.
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.
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] |
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:
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.
There are three main steps to follow before running the package program:
The following sections summarize these steps.
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.
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.
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:
These steps are discussed more completely in Modifying Client Machines.
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 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 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 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.
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:
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
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}
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.
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. |
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:
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.
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.
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.
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
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
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
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
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
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
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.
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.
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.
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.
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:
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.
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
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
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}
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 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
Modify the package Makefile files when you
The following sections provide brief examples of how to modify the Makefile file for these reasons.
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.
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 > $
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 \ ...
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.
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. |
% fs listacl [dir/file path]
% cd /afs/cellname/wsadmin/src
% cp Makefile Makefile.example
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
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.
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.
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 .
% su root Password: root_password
# 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
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
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
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.
% su root Password: root_password
# shutdown
% su root Password: root_password
# 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
`cat /.package`
Use either this argument or the -fullconfig argument.
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.
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.
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 |
The commands in the uss suite help you to automate the creation and deletion of AFS user accounts:
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.
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.
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:
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):
The following describes what happens when a uss delete command references account components that have already been deleted.
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.
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:
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:
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.
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:
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
This section discusses the three main issues you need to consider if there are existing UNIX accounts to be converted to AFS accounts.
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:
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.
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.
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 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.
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.
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:
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.
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:
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.
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:
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.
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).
G V D F E L S A X
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 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.
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.
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:
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
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.
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:
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
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.
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.
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.
The ABC Corporation example grants a 5000 KB initial quota to every new user.
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:
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.
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.
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
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
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.
The ABC Corporation example uses the value 0700 to set the mode bits on the Mailbox subdirectory to rwxr-----.
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.
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.
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
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.
The ABC Corporation example uses the value 0755 to set the mode bits on the .login file to rwxr-xr-x.
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.
The ABC Corporation example references a prototype file called .login in the directory /afs/abc.com/admin/user/proto.
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
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 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
The ABC Corporation example uses the value 0644 to set the mode bits on the passwd_user file to r-xr--r--.
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.
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
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
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
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
The A instruction in the template file enhances cell security by imposing the following restrictions on users' password choice and authentication attempts.
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
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.
The ABC Corporation example prohibits password reuse.
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.
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).
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.
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:
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 |
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
% cd template_directory
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
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.
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.
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.
This argument provides the value for the $PWEXPIRES variable in the template file.
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.
This argument provides the value for the $PART variable in the template file.
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.
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.
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.
For each instance of this argument, provide two parts in the indicated order, separated by a space:
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.
% 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. |
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.
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:
Before issuing the uss delete command, you can also perform the following optional tasks:
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.
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
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
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.
% 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. |
The uss bulk command allows you to create and delete many accounts at once. Before executing the command, you must
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:
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:
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.)
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..."
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
% cd template_directory
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
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).
% 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. |
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.
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.
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 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.
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
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 creating accounts for various types of users:
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:
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.
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.
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:
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.
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.
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:
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.
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.
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
% pts createuser <user name> [<user id>]
where
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
% vos create <machine name> <partition name> <volume name> \ [-maxquota <initial quota (KB)>]
where
% fs mkmount <directory> <volume name>
where
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.
% fs setvol <dir/file path> -offlinemsg <offline message>
where
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.
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]
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.
% pts examine <user or group name or id>
where
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.
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
% 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. |
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.
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.
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:
In summary, the recommended limit on authentication attempts is nine and lockout time 25 minutes.
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.
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
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.
The AFS distribution includes an example kpwvalid program. See the kpwvalid reference page in the IBM AFS Administration Reference.
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
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.
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.
ka> examine <name of user> User is locked until time
ka> unlock <authentication ID>
where
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
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.
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
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.
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
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:
You can use any of the three following commands to display a volume's quota:
For instructions, see Setting and Displaying Volume Quota and Current Size.
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.
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
% pts listowned <user or group name or id>
% pts rename <old name> <new name>
Repeat the command for each group. Step 3 details its syntax.
% pts rename <old name> <new name>
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.
ka> delete <name of user>
where
ka> create <name of user> initial_password: password Verifying, please re-enter initial_password: password
where
ka> quit
% vos rename <old volume name> <new volume name>
% fs rmmount <directory>
% fs mkmount <directory> <volume name>
% 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. |
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.
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
% pts listowned <user or group name or id>
% pts delete <user or group name or id>+
where
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
% vos listvldb <volume name or ID>
where
% vos remove <machine name> <partition name> <volume name or ID>
where
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
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.
% 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. |
This chapter explains how to create and maintain user, machine, and group entries in the Protection Database.
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 |
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.
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.
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.)
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.
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.
% pts membership system:administrators
% pts examine <user or group name or id>+
where
The output includes the following fields. Examples follow.
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.
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.
For a complete description of possible values for the flags, see Setting the Privacy Flags on Database Entries.
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.
% pts membership system:administrators
% pts membership <user or group name or id>+
where
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
% pts membership system:administrators
% pts listowned <user or group name or id>+
where
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
% pts membership system:administrators
% pts listentries [-users] [-groups]
where
The output is a table that includes the following columns. Examples follow.
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
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.
% pts membership system:administrators
% pts createuser -name <user name>+
where
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
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:
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.
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.
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:
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.
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. |
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.
% pts membership system:administrators
% pts creategroup -name <group name>+ [-owner <owner of the group>]
where
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:
(For a discussion of why it is useful for a group to own another group, see Using Groups Effectively.)
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.
% pts creategroup <group name>
% pts adduser -user <user name>+ -group <group name>+
% pts chown <group name> <new owner>
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:
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.
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.
% pts membership system:administrators
% pts adduser -user <user name>+ -group <group name>+
where
% pts membership system:administrators
% pts removeuser -user <user name>+ -group <group name>+
where
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:
To remove obsolete AFS IDs from ACLs, use the fs cleanacl command as described in Removing Obsolete AFS IDs from ACLs.
% pts membership system:administrators
% pts delete <user or group name or id>+
where
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:
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.
% pts membership system:administrators
% 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>
% pts chown <group name> <new owner>
where
% 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>
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:
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.
Both the group's owner and the members of the system:administrators group can change its name to another prefix-less name.
Only members of the system:administrators group can make this type of name change.
% pts membership system:administrators
% pts rename <old name> <new name>
where
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.
% pts membership system:administrators
% pts setfields -nameorid <user or group name or id>+ \ -groupquota <set limit on group creation>
where
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:
Each flag can take three possible types of values to enable a different set of users to issue the corresponding command:
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.
% pts membership system:administrators
% pts setfields <user or group name or id>+ -access <set privacy flags>
where
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:
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.
% 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.
% pts membership system:administrators
% pts setmax [-group <group max>] [-user <user max>]
where
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).
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 |
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.
The UFS mode bits data protection system and the AFS ACL system differ in the following ways:
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:
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.
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.
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)
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.
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 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.
This permission enables a user to issue the following commands:
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 three permissions in this group are meaningful with respect to files in a directory, rather than the directory itself or its subdirectories.
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.
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:
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:
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.
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.
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.
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.
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.
% fs listacl [<dir/file path>+]
where
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.
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.
% fs listacl [<dir/file path>]
% fs setacl -dir <directory>+ -acl <access list entries>+
where
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:
fs: 'filename': Not a directory
If you specify only one directory or file name, you can omit the -dir and -acl switches.
To define the permissions, provide either:
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
% fs listacl [<dir/file path>]
% fs setacl -dir <directory>+ -acl <access list entries>+ -negative
where
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
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.
% fs listacl [<dir/file path>]
% fs setacl -dir <directory>+ -acl <access list entries>+ -clear \ [-negative]
where
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:
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.
% fs listacl [<dir/file path>]
% fs copyacl -fromdir <source directory> -todir <destination directory>+ \ [-clear]
where
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.
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
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.
% fs listacl [<dir/file path>]
% fs cleanacl [<dir/file path>+]
where
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:
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.
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:
This chapter explains how to enable system administrators and operators to perform privileged AFS operations.
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 |
A fully privileged AFS system administrator has the following characteristics:
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. |
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.
The first type of AFS administrative privilege is membership . Members of the system:administrators group in the Protection Database have the following privileges:
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.
% pts membership system:administrators
where m is the shortest acceptable abbreviation of membership.
% pts membership system:administrators
% pts adduser -user <user name>+ -group system:administrators
where
% pts membership system:administrators
% pts removeuser -user <user name>+ -group system:administrators
where
Administrators who have the ADMIN flag on their Authentication Database entry can issue all kas commands, which enable them to administer 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
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...
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
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.
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.
% bos listusers <machine name>
where
% bos listusers <machine name>
% bos adduser <machine name> <user names>+
where
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.
% bos listusers <machine name>
% bos removeuser <machine name> <user names>+
where
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.
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.
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 |
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:
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 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 designates the AFS client machine that performs two functions for NFS clients:
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 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.
To learn the values of the AFSSERVER and AFSCONF variables, AFS command interpreters consult the following three sources in sequence:
(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.
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.
To act as an NFS/AFS translator machine, a machine must configured as follows:
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.
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.
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.
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.
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.
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.
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.
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.
% su root Password: root_password
The following example enables any NFS client machine to mount the machine's /afs, /usr, and /usr2 directories:
/afs /usr /usr2
share -F nfs -o rw -d "root" / share -F nfs -o rw -d "afs gateway" /afs
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
# shutdown appropriate_options
% su root Password: root_password
# fs exportafs nfs [-start {on | off}} ] [-convert {on | off}] [-uidcheck {on | off}] [-submounts {on | off}]
If this argument is omitted, the default value is off.
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.
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.
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.
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. |
% su root Password: root_password
# mkdir /afs
mount -o hard,intr,timeo=300 translator_machine:/afs /afs
where
NFS server translator is not responding, still trying
With a soft mount, it reduces the number of actual errors returned on timed-out requests.
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. |
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.
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.
% fs sysname
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.
% knfs -host <host name> [-id <user ID (decimal)>] [-sysname <host's '@sys' value>]
where
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
% knfs -host <host name> [-id <user ID (decimal)>] -tokens
where
% knfs -host <host name> [-id <user ID (decimal)>] -unlog
where
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 commands that belong to suites have the following structure:
command_suite operation_code -switch <value>[+] [-flag]
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.
The term option refers to both arguments and flags, which are described in the following sections.
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:
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 ([ ]).
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.
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
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:
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.
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.
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.
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
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.
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:
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).
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.
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.
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
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.
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:
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
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
Cache Manager statistics fields are classified into the following sections and groups:
All Cache Manager variables categorized under these sections and groups names are listed below.
Performance Statistics Group (PerfStats_group)
Miscellaneous Group (misc_group)
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.
File Server Up/Down Statistics in Other Cells Group (FS_upDown_OC_group)
VL Server Up/Down Statistics in Same Cell Group (VL_upDown_SC_group)
VL Server Up/Down Statistics in Other Cells Group (VL_upDown_DC_group)
File Server RPC Operation Timings Group (FS_RPCopTimes_group)
File Server RPC Operation Errors Group (FS_RPCopErrors_group)
File Server RPC Transfer Timings Group (FS_RPCopBytes_group)
Cache Manager RPC Operation Timings Group (CM_RPCopTimes_group)
Authentication Information for Cache Manager Group (Auth_Stats_group)
Unreplicated File Access Group (Access_Stats_group)
File Server statistics are classified into the following sections and groups:
All File Server variables categorized under the above sections and groups names are listed below.
Vnode Cache Group (VnodeCache_group)
Directory Package Group (Directory_group)
Rx Group (Rx_group)
Host Module Fields Group (HostModule_group)
Miscellaneous Variables Group (misc_group)
Individual RPC Operation Timings Group (RPCopTimes_group)
Byte Information for Certain RPC Operations Group (RPCopBytes_group)
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.
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:
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). |
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. |
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. |
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? |
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. |
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. |
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. |
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. |
Version 3.6
Document Number GC09-4562-00
First Edition (April 2000)
This edition applies to:
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.
This chapter describes the purpose, organization, and conventions of this document.
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.
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:
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.
The following documents are included in the AFS documentation set.
IBM AFS Administration Guide
This guide describes the concepts and procedures that a system administrator must know to manage an AFS cell. It assumes familiarity with UNIX, but requires no previous knowledge of AFS.
The first chapters of the IBM AFS Administration Guide present basic concepts and guidelines. Understanding them is crucial to successful administration of an AFS cell. The remaining chapters in the guide provide step-by-step instructions for specific administrative tasks, along with discussions of the concepts important to that particular task.
IBM AFS Quick Beginnings
This guide provides instructions for installing AFS server and client machines. It is assumed that the installer is an experienced UNIX (R) system administrator.
For predictable performance, machines must be installed and configured in accordance with the instructions in this guide.
IBM AFS Release Notes
This document provides information specific to each release of AFS, such as a list of new features and commands, a list of requirements and limitations, and instructions for upgrading server and client machines.
IBM AFS User Guide
This guide presents the basic concepts and procedures necessary for using AFS effectively. It assumes that the reader has some experience with UNIX, but does not require familiarity with networking or AFS.
The guide explains how to perform basic functions, including authenticating, changing a password, protecting AFS data, creating groups, and troubleshooting. It provides illustrative examples for each function and describes some of the differences between the UNIX file system and AFS.
This document uses the following typographical conventions:
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.
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:
For a description of the format and contents of each file, see its reference page.
Note for Windows users: Some files described in this document possibly do not exist on machines that run a Windows operating system. Also, Windows uses a backslash ( \ ) rather than a forward slash ( / ) to separate the elements in a pathname.
Related Information
Controller files:
Volume header files:
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
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
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
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
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:
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.
In addition to server process entries, the BosConfig file specifies the times at which the BOS Server performs two types of automatic process restarts:
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:
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:
Related Information
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
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:
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:
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 AUTOQUERY Instruction
The AUTOQUERY instruction takes a boolean value as its argument, in the following format:
AUTOQUERY {YES | NO}
When the value is YES, the Tape Coordinator checks for the MOUNT instruction in the configuration file when it needs to read the first tape involved in an operation. As described for that instruction, it then either prompts for the tape or invokes the specified routine to mount the tape. This is the default behavior if the AUTOQUERY instruction does not appear in the configuration file.
When the value is NO, the Tape Coordinator assumes that the first tape required for an operation is already in the drive. It does not prompt the operator or invoke the MOUNT routine unless there is an error in accessing the first tape. This setting is equivalent in effect to including the -noautoquery flag to the butc command.
Note that the setting of the AUTOQUERY instruction controls the Tape Coordinator's behavior only with respect to the first tape required for an operation. For subsequent tapes, the Tape Coordinator always checks for the MOUNT instruction. It also refers to the MOUNT instruction if it encounters an error while attempting to access the first tape.
The BUFFERSIZE Instruction
The BUFFERSIZE instruction takes an integer value, and optionally units, in the following format:
BUFFERSIZE size[{k | K | m | M | g | G}]
where size specifies the amount of memory the Tape Coordinator allocates to use as a buffer during both dump and restore operations. The default unit is bytes, but use k or K to specify kilobytes, m or M for megabytes, and g or G for gigabytes. There is no space between the sizevalue and the units letter.
By default, the Tape Coordinator uses a 16 KB buffer during dump operations. As it receives volume data from the Volume Server, the Tape Coordinator gathers 16 KB of data in the buffer before transferring the entire 16 KB to the tape device or backup data file. Similarly, during a restore operation the Tape Coordinator by default buffers 32 KB of data from the tape device or backup data file before transferring the entire 32 KB to the Volume Server for restoration into the file system. Buffering makes the volume of data flowing to and from a tape device more even and so promotes tape streaming, which is the most efficient way for a tape device to operate.
In a normal network configuration, the default buffer sizes are usually large enough to promote tape streaming. If the network between the Tape Coordinator machine and file server machines is slow, it can help to increase the buffer size.
The FILE Instruction
The FILE instruction takes a boolean value as its argument, in the following format:
FILE {NO | YES}
When the value is NO, the Tape Coordinator writes to a tape device during a dump operation and reads from one during a restore operation. This is the default behavior if the FILE instruction does not appear in the configuration file.
When the value is YES, the Tape Coordinator writes volume data to a backup data file on the local disk during a dump operation and reads volume data from a file during a restore operation. If the file does not exist when the Tape Coordinator attempts to access it to write a dump, the Tape Coordinator creates it. For a restore operation to succeed, the file must exist and contain volume data previously written to it by a backup dump operation.
When the value is YES, the backup data file's complete pathname must appear (instead of a tape drive device name) in the third field of the corresponding port offset entry in the local /usr/afs/backup/tapeconfig file. If the field instead refers to a tape device, dump operations appear to succeed but are inoperative. It is not possible to restore data that was accidently dumped to a tape device while the FILE instruction was set to YES. (In the same way, if the FILE instruction is set to NO, the tapeconfig entry must refer to an actual tape device.)
Rather than put an actual file pathname in the third field of the tapeconfig file, however, the recommended configuration is to create a symbolic link in the /dev directory that points to the actual file pathname, and record the symbolic link in this field. This configuration has a couple of advantages:
If the third field in the tapeconfig file names the actual file, there is no way to recover from exhausting the space on the partition that houses the backup data file. It is not possible to change the tapeconfig file in the middle of an operation.
When writing to a backup data file, the Tape Coordinator writes data at 16 KB offsets. If a given block of data (such as the marker that signals the beginning or end of a volume) does not fill the entire 16 KB, the Tape Coordinator still skips to the next offset before writing the next block. In the output of a backup dumpinfo command issued with the -id option, the value in the Pos column is the ordinal of the 16-KB offset at which the volume data begins, and so is not generally only one higher than the position number on the previous line, as it is for dumps to tape.
The MOUNT Instruction
The MOUNT instruction takes a pathname as its argument, in the following format:
MOUNT filename
The referenced executable file must reside on the local disk and contain a shell script or program that directs an automated tape device, such as a jukebox or stacker, to mount a tape (insert it into the tape reader). The operator must write the routine to invoke the mount command specified by the device's manufacturer; AFS does not include any scripts, although an example appears in the following Examples section. The script or program inherits the Tape Coordinator's AFS authentication status.
When the Tape Coordinator needs to mount a tape, it checks the configuration file for a MOUNT instruction. If there is no MOUNT instruction, the Tape Coordinator prompts the operator to insert a tape before it attempts to open the tape device. If there is a MOUNT instruction, the Tape Coordinator executes the routine in the referenced file. The routine invoked by the MOUNT instruction inherits the local identity (UNIX UID) and AFS tokens of the butc command's issuer.
There is an exception to this sequence: if the AUTOQUERY NO instruction appears in the configuration file, or the -noautoquery flag was included on the butc command, then the Tape Coordinator assumes that the operator has already inserted the first tape needed for a given operation. It attempts to read the tape immediately, and only checks for the MOUNT instruction or prompts the operator if the tape is missing or is not the required one.
When the Tape Coordinator invokes the routine indicated by the MOUNT instruction, it passes the following parameters to the routine in the indicated order:
The routine invoked by the MOUNT instruction must return an exit code to the Tape Coordinator:
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:
Privilege Required
The file is protected by UNIX mode bits. Creating the file requires the w (write) and x (execute) permissions on the /usr/afs/backup directory. Editing the file requires the w (write) permission on the file.
Examples
The following example configuration files demonstrate one way to structure a configuration file for a stacker or backup dump file. The examples are not necessarily appropriate for a specific cell; if using them as models, be sure to adapt them to the cell's needs and equipment.
Example CFG_device_name File for Stackers
In this example, the administrator creates the following entry for a tape stacker called stacker0.1 in the /usr/afs/backup/tapeconfig file. It has port offset 0.
2G 5K /dev/stacker0.1 0
The administrator includes the following five lines in the /usr/afs/backup/CFG_stacker0.1 file. To review the meaning of each instruction, see the preceding Description section.
MOUNT /usr/afs/backup/stacker0.1 UNMOUNT /usr/afs/backup/stacker0.1 AUTOQUERY NO ASK NO NAME_CHECK NO
Finally, the administrator writes the following executable routine in the /usr/afs/backup/stacker0.1 file referenced by the MOUNT and UNMOUNT instructions in the CFG_stacker0.1 file.
#! /bin/csh -f set devicefile = $1 set operation = $2 set tries = $3 set tapename = $4 set tapeid = $5 set exit_continue = 0 set exit_abort = 1 set exit_interactive = 2 #-------------------------------------------- if (${tries} > 1) then echo "Too many tries" exit ${exit_interactive} endif if (${operation} == "unmount") then echo "UnMount: Will leave tape in drive" exit ${exit_continue} endif if ((${operation} == "dump") |\ (${operation} == "appenddump") |\ (${operation} == "savedb")) then stackerCmd_NextTape ${devicefile} if (${status} != 0)exit${exit_interactive} echo "Will continue" exit ${exit_continue} endif if ((${operation} == "labeltape") |\ (${operation} == "readlabel")) then echo "Will continue" exit ${exit_continue} endif echo "Prompt for tape" exit ${exit_interactive}
This routine uses two of the parameters passed to it by the Backup System: tries and operation. It follows the recommended practice of prompting for a tape if the value of the tries parameter exceeds one, because that implies that the stacker is out of tapes.
For a backup dump or backup savedb operation, the routine calls the example stackerCmd_NextTape function provided by the stacker's manufacturer. Note that the final lines in the file return the exit code that prompts the operator to insert a tape; these lines are invoked when either the stacker cannot load a tape or a the operation being performed is not one of those explicitly mentioned in the file (such as a restore operation).
Example CFG_device_name File for Dumping to a Backup Data File
In this example, the administrator creates the following entry for a backup data file called HSM_device in the /usr/afs/backup/tapeconfig file. It has port offset 20.
1G 0K /dev/HSM_device 20
The administrator includes the following lines in the /usr/afs/backup/CFG_HSM_device file. To review the meaning of each instruction, see the preceding Description section.
MOUNT /usr/afs/backup/file FILE YES ASK NO
Finally, the administrator writes the following executable routine in the /usr/afs/backup/file file referenced by the MOUNT instruction in the CFG_HSM_device file, to control how the Tape Coordinator handles the file.
#! /bin/csh -f set devicefile = $1 set operation = $2 set tries = $3 set tapename = $4 set tapeid = $5 set exit_continue = 0 set exit_abort = 1 set exit_interactive = 2 #-------------------------------------------- if (${tries} > 1) then echo "Too many tries" exit ${exit_interactive} endif if (${operation} == "labeltape") then echo "Won't label a tape/file" exit ${exit_abort} endif if ((${operation} == "dump") |\ (${operation} == "appenddump") |\ (${operation} == "restore") |\ (${operation} == "savedb") |\ (${operation} == "restoredb")) then /bin/rm -f ${devicefile} /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile} if (${status} != 0) exit ${exit_abort} endif exit ${exit_continue}
Like the example routine for a tape stacker, this routine uses the tries and operation parameters passed to it by the Backup System. The tries parameter tracks how many times the Tape Coordinator has attempted to access the file. A value greater than one indicates that the Tape Coordinator cannot access it, and the routine returns exit code 2 (exit_interactive), which results in a prompt for the operator to load a tape. The operator can use this opportunity to change the name of the backup data file specified in the tapeconfig file.
The primary function of this routine is to establish a link between the device file and the file to be dumped or restored. When the Tape Coordinator is executing a backup dump, backup restore, backup savedb, or backup restoredb operation, the routine invokes the UNIX ln -s command to create a symbolic link from the backup data file named in the tapeconfig file to the actual file to use (this is the recommended method). It uses the value of the tapename and tapeid parameters to construct the file name.
Related Information
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:
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:
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
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:
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
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
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
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:
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 AFS Administration Guide
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
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:
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
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
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:
As it initializes, the File Server constructs a list of interfaces to register, from the /usr/afs/local/NetInfo file if it exists, or from the list of interfaces configured with the operating system otherwise. The File Server then removes from the list any addresses that appear in the NetRestrict file, if it exists. The File Server records the resulting list in the /usr/afs/local/sysid file and registers the interfaces in the VLDB. The database server processes use a similar procedure when initializing, to determine which interfaces to use for communication with the peer processes on other database machines in the cell.
The NetRestrict file is in ASCII format. One IP address appears on each line, in dotted decimal format. The order of the addresses is not significant. The value 255 is a wildcard that represents all possible addresses in that field. For example, the value 192.12.105.255 indicates that the Cache Manager does not register any of the addresses in the 192.12.105 subnet.
To display the File Server interface addresses registered in the VLDB, use the vos listaddrs command.
Related Information
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:
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:
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
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
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
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
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 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
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
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
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:
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
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:
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
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.
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
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
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
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
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
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
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
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:
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
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
Records failed authentication attempts
Description
The file kaserverauxdb records failed authentication attempts for the local Authentication Server. The server creates it automatically in the /usr/afs/local directory by default; use the -localfiles argument to the kaserver command to specify an alternate directory.
The kaserverauxdb file is an internal database used by the Authentication Server to prevent access by users who have exceeded the limit on failed authentication attempts defined in their Authentication Database entry. The Authentication Server refuses further attempts to authenticate to an account listed in the database until either an AFS system administrator issues the kas unlock command to unlock the account, or the timeout period defined in the user's Authentication Database entry passes.
The kaserverauxdb file is in binary format, so its contents are not directly accessible. However, the output from the kas examine command reports an account's maximum number of failed attempts, the lockout time, and whether the account is currently locked.
Related Information
kaserver.DB0 and kaserver.DBSYS1
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
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
Lists file server machine interface addresses registered in VLDB
Description
The sysid file records the network interface addresses that the File Server (fileserver process) registers in the Volume Location Database (VLDB) for the local file server machine.
Each time the File Server restarts, it builds a list of interfaces on the local machine by reading the /usr/afs/local/NetInfo file, if it exists. If the file does not exist, the File Server uses the list of network interfaces configured with the operating system. It then removes from the list any addresses that appear in the /usr/afs/local/NetRestrict file, if it exists. The File Server records the resulting list in the binary-format sysid file and registers the interfaces in the VLDB.
When the Cache Manager requests volume location information, the Volume Location (VL) Server provides all of the interfaces registered for each server machine that houses the volume. This enables the Cache Manager to make use of multiple addresses when accessing AFS data stored on a multihomed file server machine.
Cautions
The sysid file is unique to each file server machine, and must not be copied from one machine to another. If it is a common practice in the cell to copy the contents of the /usr/afs/local directory from an existing file server machine to a newly installed one, be sure to remove the sysid file from the new machine before starting the fs trio of processes, which includes the fileserver process.
Some versions of AFS limit how many of a file server machine's interface addresses that can be registered. Consult the IBM AFS Release Notes.
Related Information
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
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.
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.
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.
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
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
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:
The parameters fs, cm, field_name, threshold_val, and arg1 through argn correspond to the values with the same name on the thresh line. The host_name parameter identifies the file server or client machine where the statistic has crossed the threshold, and the actual_val parameter is the actual value of field_name that 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.
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.
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
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.
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
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
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
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.
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.
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.
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
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.
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.
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.
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
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.
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.
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:
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
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
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
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
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.
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.
Corresponding argument to the uss add command: -user. Corresponding variable in the template file: $USER.
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.
Corresponding argument to the uss add command: -pass. Corresponding variable in the template file: none.
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.
Corresponding argument to the uss add command: -server. Corresponding variable in the template file: $SERVER.
/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.
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.
Corresponding argument to the uss add command: -uid. Corresponding variable in template: $UID.
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
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
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.
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.
The instruction has the following syntax:
A username password_lifetime password_reuse failures locktime
where
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.
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.
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 instruction has the following syntax:
D pathname mode_bits owner ACL
where
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.
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
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.
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
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.
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
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
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
/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.
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. |
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
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
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.
In addition, there are several commands that do not belong to suites.
AFS commands that belong to suites have the following structure:
command_suite operation_code -switch <value>[+] [-flag]
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.
The term option refers to both arguments and flags, which are described in the following sections.
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:
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 ([ ]).
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.
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
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:
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.
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.
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
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:
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.
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:
If no operation code is specified, the help operation code displays the first line (short description) for every operation code in the suite:
% command_suite help
If the issuer specifies one or more operation codes, the help operation code displays each command's complete online entry (short description, alias if any, and syntax):
% command_suite help operation_code+
The -help flag displays a command's syntax but not the short description or alias:
% command_name -help
The apropos operation code displays the short description of any command in a suite whose operation code or short description includes the specified keyword:
% command_suite apropos "<help string>"
The following example command displays the complete online help entry for the fs setacl command:
% fs help setacl fs setacl: set access control list aliases: sa Usage: fs setacl -dir <directory>+ -acl <access list entries>+ [-clear] [-negative] [-id] [-if] [-help]
To see only the syntax statement, use the -help flag:
% fs setacl -help Usage: fs setacl -dir <directory>+ -acl <access list entries>+ [-clear] [-negative] [-id] [-if] [-help]
In the following example, a user wants to display the quota for her home volume. She knows that the relevant command belongs to the fs suite, but cannot remember the operation code. She uses quota as the keyword:
% fs apropos quota listquota: list volume quota quota: show volume quota usage setquota: set volume quota
The following illustrates the error message that results if no command name or short description contains the keyword:
% fs apropos "list quota" Sorry, no commands found
Privilege Required
Many AFS commands require one or more types of administrative privilege. See the reference page for each command.
Related Information
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:
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.
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.
For a memory cache, the following arguments to the afsd command override the value in the cacheinfo file:
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.
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.
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.
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.)
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.
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
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.
Note: | Provide this argument only on a machine that runs AIX with VM integration. |
Examples
The afsd command is normally included in the machine's AFS initialization file, rather than typed at the command shell prompt. For most disk caches, the appropriate form is
/usr/vice/etc/afsd
The following command is appropriate when enabling a machine to act as an NFS/AFS Translator machine serving more than five users.
/usr/vice/etc/afsd -daemons 4 -rmtsys
The following command initializes a memory cache and sets chunk size to 16 KB (214).
/usr/vice/etc/afsd -memcache -chunksize 14
Privilege Required
The issuer must be logged in as the local superuser root.
Related Information
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:
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 afsmonitor screens format successfully both on so-called dumb terminals and in windowing systems that emulate terminals. For the output to looks its best, the display environment needs to support reverse video and cursor addressing. Set the TERM environment variable to the correct terminal type, or to a value that has characteristics similar to the actual terminal type. The display window or terminal must be at least 80 columns wide and 12 lines long.
The afsmonitor program must run in the foreground, and in its own separate, dedicated window or terminal. The window or terminal is unavailable for any other activity as long as the afsmonitor program is running. Any number of instances of the afsmonitor program can run on a single machine, as long as each instance runs in its own dedicated window or terminal. Note that it can take up to three minutes to start an additional instance.
Options
Output
The afsmonitor program displays its data on three screens:
Fields at the corners of every screen display the following information:
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.
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:
A list of the machines being monitored follows. If there are any alerts on a machine, the number of them appears in square brackets to the left of the hostname. If a process failed to respond to the last probe, the letters PF (probe failure) appear in square brackets to the left of the hostname.
The File Servers Screen
The File Servers screen displays the values collected at the most recent probe for File Server statistics.
A summary line at the top of the screen (just below the standard program version and screen title blocks) specifies the number of monitored File Servers, the number of alerts, and the number of machines affected by the alerts.
The first column always displays the hostnames of the machines running the monitored File Servers.
To the right of the hostname column appear as many columns of statistics as can fit within the current width of the display screen or window; each column requires space for 10 characters. The name of the statistic appears at the top of each column. If the File Server on a machine did not respond to the most recent probe, a pair of dashes (--) appears in each column. If a value exceeds its configured threshold, it is highlighted in reverse video. If a value is too large to fit into the allotted column width, it overflows into the next row in the same column.
The Cache Managers Screen
The Cache Managers screen displays the values collected at the most recent probe for Cache Manager statistics.
A summary line at the top of the screen (just below the standard program version and screen title blocks) specifies the number of monitored Cache Managers, the number of alerts, and the number of machines affected by the alerts.
The first column always displays the hostnames of the machines running the monitored Cache Managers.
To the right of the hostname column appear as many columns of statistics as can fit within the current width of the display screen or window; each column requires space for 10 characters. The name of the statistic appears at the top of each column. If the Cache Manager on a machine did not respond to the most recent probe, a pair of dashes (--) appears in each column. If a value exceeds its configured threshold, it is highlighted in reverse video. If a value is too large to fit into the allotted column width, it overflows into the next row in the same column.
Writing to an Output File
Include the -output argument to name the file into which the afsmonitor program writes all of the statistics it collects. The output file can be useful for tracking performance over long periods of time, and enables the administrator to apply post-processing techniques that reveal system trends. The AFS distribution does not include any post-processing programs.
The output file is in ASCII format and records the same information as the File Server and Cache Manager display screens. Each line in the file uses the following format to record the time at which the afsmonitor program gathered the indicated statistic from the Cache Manager (CM) or File Server (FS) running on the machine called host_name. If a probe failed, the error code -1 appears in the statistic field.
time host_name CM|FS statistic
If the administrator usually reviews the output file manually, rather than using it as input to an automated analysis program or script, including the -detail flag formats the data in a more easily readable form.
Examples
For examples of commands, display screens, and configuration files, see the section about the afsmonitor program in the IBM AFS Administration Guide.
Privilege Required
None
Related Information
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:
The backup command interpreter interacts with two other processes:
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.
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.
Use this flag only when issuing a command on a server machine; client machines do not usually have a /usr/afs/etc/KeyFile file. The issuer of a command that includes this flag must be logged on to the server machine as the local superuser root. The flag is useful for commands invoked by an unattended application program, such as a process controlled by the UNIX cron utility or by a cron entry in the machine's /usr/afs/local/BosConfig file. It is also useful if an administrator is unable to authenticate to AFS but is logged in as the local superuser root.
Do not combine the -cell and -localauth options. A command on which the -localauth flag is included always runs in the local cell (as defined in the server machine's local /usr/afs/etc/ThisCell file), whereas a command on which the -cell argument is included runs in the specified foreign cell.
The -localauth argument is not available on commands issued in interactive mode. The local identity and AFS tokens with which the backup command interpreter enters interactive mode apply to all commands issued during the interactive session.
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 Backup System does not reserve UDP sockets. If another application is already using the Tape Coordinator's socket when it tries to start, the butc process fails and the following error message appears at the shell prompt:
bind: Address already in use rxi_GetUDPSocket: bind failed
To issue any backup command that accesses the Backup Database only, the issuer must be listed in the /usr/afs/etc/UserList file on every machine where the Backup Server is running. To issue any backup command that accesses volume data, the issuer must appear in the UserList file on every Backup Server machine, every Volume Location (VL) Server machine, and every file server machine that houses affected volumes. By convention, a common UserList file is distributed to all database server and file server machines in the cell. See the chapter on privileged users in the IBM AFS Administration Guide for more information on this type of privilege.
If the -localauth flag is included, the user must instead be logged on as the local superuser root on the server machine where the backup command is issued.
Related Information
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:
Options
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.
[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. |
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
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
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
Examples
The following command creates an entry in the Backup Database that assigns port offset number 4 to a Tape Coordinator running on the machine backup1.abc.com:
% backup addhost -tapehost backup1.abc.com -portoffset 4
The following command creates a Backup Database entry that assigns port offset number 0 to a Tape Coordinator on the machine backup3.abc.com:
% backup addhost backup3.abc.com
Privilege Required
The issuer must be listed in the /usr/afs/etc/UserList file on every machine where the Backup Server is running, or must be logged onto a server machine as the local superuser root if the -localauth flag is included.
Related Information
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
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
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
Examples
The following command adds a volume entry to the volume set called sys. The entry matches all volumes on any machine or partition whose names begin with the string sun4x_56 followed by a period:
backup> addvolentry sys .* .* sun4x_56\..*
The following command adds a volume entry to the volume set called fs2, to match all volumes on the /vicepb partition of file server machine fs2.abc.com. Because it is issued at the shell prompt, double quotes surround the metacharacters in the -volumes argument. (The command is shown here on two lines only for legibility reasons.)
% backup addvolentry -name fs2 -server fs2.abc.com \ -partition /vicepb -volumes ".*"
The chapter in the IBM AFS Administration Guide about configuring the AFS Backup System presents additional examples as well as advice on grouping volumes.
Privilege Required
The issuer must be listed in the /usr/afs/etc/UserList file on every machine where the Backup Server is running, or must be logged onto a server machine as the local superuser root if the -localauth flag is included.
Related Information
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
Examples
The following command creates a volume set called sys:
% backup addvolset sys
Privilege Required
The issuer must be listed in the /usr/afs/etc/UserList file on every machine where the Backup Server is running, or must be logged onto a server machine as the local superuser root if the -localauth flag is included.
Related Information
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
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
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
Output
The command displays one of the following two messages:
The -detail flag provides additional information:
Examples
The following command confirms that the Backup Database is undamaged:
% backup dbverify Database OK
The following command confirms that the Backup Database is undamaged and that it has no orphan blocks or invalid Tape Coordinator entries. The Backup Server running on the machine db1.abc.com checked its copy of the Database.
% backup dbverify -detail Database OK Orphan blocks 0 Database checker was db1.abc.com
Privilege Required
The issuer must be listed in the /usr/afs/etc/UserList file on every machine where the Backup Server is running, or must be logged onto a server machine as the local superuser root if the -localauth flag is included.
Related Information
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
Examples
The following command deletes the dump level /sunday1/monday1 from the dump hierarchy, along with any of its child dump levels.
% backup deldump /sunday1/monday1
Privilege Required
The issuer must be listed in the /usr/afs/etc/UserList file on every machine where the Backup Server is running, or must be logged onto a server machine as the local superuser root if the -localauth flag is included.
Related Information
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
Provide either this argument or the -to (and optionally -from) argument.
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. |
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. |
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
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
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
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
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
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
Examples
The following command deletes the fourth volume entry from the volume set called sys:
% backup delvolentry -name sys -entry 4
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
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
Examples
The following command deletes the volume set called user and all volume entries in it:
% backup delvolset user
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
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.
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.
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
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.
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
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 an affected volume. If the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser root.
Related Information
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:
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.
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:
Can't overwrite tape containing the dump in progress
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
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).
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. |
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.
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
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 an affected volume. If the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser root.
Related Information
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
Output
If the -ndumps argument is provided, the output presents the following information in table form, with a separate line for each dump:
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:
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:
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:
If both the -id and -verbose options are provided, the output is divided into several sections:
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
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
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
Output
The online help entry for each backup command consists of the following two or three lines:
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
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:
To exit an interactive session, issue the (backup) quit command.
Options
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
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
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 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
The line for a pending or running operation of any other type has the following format:
Job job_ID: operation status
where
volume_set_name.dump_level_name
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
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:
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
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
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
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).
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.
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.
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
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
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
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
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
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
Output
After a Tape hosts: header, the output reports two things about each Tape Coordinator currently defined in the Backup Database:
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
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
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
Options
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
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
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
Examples
The following command exits interactive mode:
backup> quit %
Privilege Required
None
Related Information
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.
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
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:
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 10242).
% 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
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
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
Examples
The following example shows the Backup Database being restored from the Tape Coordinator with port offset 0:
% backup restoredb
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 AFS Administration Guide
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
Provide one of two values:
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: | 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. |
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
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
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:
Options
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:
The volume header contains the following fields:
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
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
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.
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:
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
[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. |
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
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
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
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
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.
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
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
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
Output
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:
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
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:
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.
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.
Options
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.
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. |
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.
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
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 an affected volume. If the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser root.
Related Information
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:
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.
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.
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.
Options
Each volume's entry must appear on its own (unbroken) line in the file, and have the following format:
machine partition volume [comments...]
where
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.
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.
Output
If the -n flag is not provided, the command displays a unique task ID number for the operation, in two places:
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
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
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 an affected volume. If the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser root.
Related Information
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:
The BOS Server and the bos commands use and maintain the following configuration and log files:
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.
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.
Use this flag only when issuing a command on a server machine; client machines do not usually have a /usr/afs/etc/KeyFile file. The issuer of a command that includes this flag must be logged on to the server machine as the local superuser root. The flag is useful for commands invoked by an unattended application program, such as a process controlled by the UNIX cron utility or by a cron entry in the machine's /usr/afs/local/BosConfig file. It is also useful if an administrator is unable to authenticate to AFS but is logged in as the local superuser root.
Do not combine the -cell and -localauth options. A command on which the -localauth flag is included always runs in the local cell (as defined in the server machine's local /usr/afs/etc/ThisCell file), whereas a command on which the -cell argument is included runs in the specified foreign cell. Also, do not combine the -localauth and -noauth flags.
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:
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
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
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.
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
IBM AFS Quick Beginnings
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
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.
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
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
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
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.
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
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
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
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
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
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:
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
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
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);
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
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
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
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
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
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
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
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.
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
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
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.
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
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
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:
Use the bos setrestart command to set the restart times.
Options
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:
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
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
Output
The online help entry for each bos command consists of the following two or three lines:
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
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
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).
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
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
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
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.
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
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
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.
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
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
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
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.
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
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:
(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
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
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
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
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.
Options
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.
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
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
IBM AFS Quick Beginnings
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
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.
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
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
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
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.
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
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
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:
This command does not change a process's status flag in the BosConfig file.
Options
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
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
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:
Use the indicated arguments to salvage a specific number of volumes:
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.
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.
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
/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 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.
_ _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.
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
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
IBM AFS Administration Guide
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
Examples
The following example disables authorization checking on the machine fs7.abc.com:
% bos setauth -server fs7.abc.com -authrequired off
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
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:
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
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
IBM AFS Quick Beginnings
IBM AFS Administration Guide
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:
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
There are four acceptable values for either type of restart setting:
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.
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
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
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
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
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
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
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
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
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
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
To start a process and set its BosConfig status flag to Run, use the bos start command instead.
Options
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
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
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
Options
Output
The output for a process includes at least one line, which reports one of the following as the process's current status:
If one of the following special circumstances applies to the process, the indicated message appears in its entry:
The entry for the fs process always includes a second line to report the process's Auxiliary status, which is one of the following:
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:
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
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
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
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
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
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).
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
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
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:
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
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
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
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
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 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:
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
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.
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
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:
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 DFSTM File Server from tickets for an AFS File Server.
Options
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 requested lifetime must be smaller than any of the DCE cell's determinants for ticket lifetime; see the discussion in the preceding Description section.
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
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
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
dm pass reference page in IBM AFS/DFS Migration Toolkit Administration Guide and Reference
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.
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:
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
The maximum number of threads can differ in each release of AFS. Consult the IBM AFS Release Notes for the current release.
File Server is running at time.
Note: | The File Server always implicitly grants the a permission to the system:administrators group, even if you use the none value. |
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. |
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. |
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
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
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
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:
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
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:
fs setserverprefs, fs sysname, and fs wscell
fs whereis, and fs whichcell
The Cache Manager and the fs commands use and maintain the following configuration files:
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.
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:
Related Information
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
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
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:
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:
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
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
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
Output
The following message confirms that the command ran successfully.
All volumeID/name mappings checked.
Privilege Required
None
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
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.
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
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:
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
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.
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
IBM AFS/DFS Migration Toolkit Administration Guide and Reference
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
Output
The output reports the following information about the volume and partition that houses each file or directory:
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
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
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
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,
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
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
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:
Options
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.
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.
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
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:
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
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
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
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
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
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
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:
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
Examples
The following command flushes from the cache all data fetched from the volume that contains the current working directory:
% fs flushvolume
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
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
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
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
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
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.
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.
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
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
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
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
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
Output
The online help entry for each fs command consists of the following two or three lines:
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
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
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:
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
IBM AFS/DFS Migration Toolkit Administration Guide and Reference
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
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
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
Output
The output displays information about the volume that houses each specified directory or file, in a tabular format that uses the following headers:
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
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
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
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
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
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:
Disabling messaging completely is not recommended, because the messages provide useful status and warning information.
Options
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
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:
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.
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.
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.
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. |
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.
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
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.
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.
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
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
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
IBM AFS/DFS Migration Toolkit Administration Guide and Reference
IBM AFS/DFS Migration Toolkit Administration Installation and Configuration Guide
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
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
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
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
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.
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
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
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.
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:
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.
This argument is not supported for DFS files or directories, because DFS does not implement negative ACL permissions.
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
IBM AFS/DFS Migration Toolkit Administration Guide and Reference
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
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
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
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
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 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 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.)
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.
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
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
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
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.
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.
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
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.
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:
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):
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
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.
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.
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.
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.
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
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
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.
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.
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
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:
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
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
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
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
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
IBM AFS Quick Beginnings
IBM AFS Administration Guide
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
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
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
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
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
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
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:
fstrace clear, fstrace lslog, fstrace setlog
fstrace lsset and fstrace setset
Options
All fstrace commands accept the following optional flag. It is listed in the command descriptions and described in detail here:
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
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
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
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
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
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
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.
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
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
Use this message to determine the actual clock time associated with each log message. Determine the actual time as follows:
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
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
Output
The online help entry for each fstrace command consists of two or three lines:
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
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
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
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
Output
The output lists the available event sets and the status of each, in the following format:
Available sets: cm {active | inactive | dormant}
where
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
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
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
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
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
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:
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
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
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.
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.
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
UNIX manual page for inetd
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
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
kaserver.DB0 and kaserver.DBSYS1
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:
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:
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.
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.
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
kaserver.DB0 and kaserver.DBSYS1
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
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
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
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
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
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
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
Output
The output includes:
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
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
Examples
The following command discards all of the issuer's tickets.
% kas forgetticket
Privilege Required
None, and no password is required.
Related Information
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
Output
The online help entry for each kas command consists of the following two or three lines:
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
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:
There are several consequences of entering interactive mode:
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
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
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:
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
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
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:
Options
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
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
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
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
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
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:
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:
Options
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).
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).
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.
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.
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
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:
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
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
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
Output
The information in the output includes:
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
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
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
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
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
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:
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
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.
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
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
kaserver.DB0 and kaserver.DBSYS1
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
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:
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
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 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
If this argument is omitted, the command is executed in the local cell, as defined
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.
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
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
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
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:
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
Old password: current_password
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
By default, the command is executed in the local cell, as defined
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
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:
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
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
Provide this argument or the -fullconfig argument.
Provide this argument or the -config argument.
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
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
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
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
Output
The online help entry for each package command consists of the following two or three lines:
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
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
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
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.
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
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
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 Protection Database.
Privilege Required
The issuer must be logged in as the local superuser root.
Related Information
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:
pts listowned, pts membership, and pts removeuser
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.
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
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
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):
Related Information
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
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
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
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
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:
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
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 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.
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
Related Information
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
Do not define a machine entry with the name 0.0.0.0 to match every machine. The system:anyuser group is equivalent.
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.
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
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:
To remove a user or machine from a group without actually deleting the entry, use the pts removeuser command.
Options
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
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
Output
The output for each entry consists of two lines that include the following fields:
Each flag can take three possible types of values to enable a different set of users to issue the corresponding command:
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.
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:
Related Information
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
Output
The online help entry for each pts command consists of the following two or three lines:
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
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
Output
The output includes a line for each entry, with information in four columns that have the following headers:
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
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
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
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
A value of 0 (zero) lists group entries for groups whose owners no longer have entries in the Protection Database.
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):
Related Information
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
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):
Related Information
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
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):
(It is not possible to set the fifth flag to uppercase R.)
Related Information
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
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
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
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.
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
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
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
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:
Options
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
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
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:
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.
Options
Consult the UNIX manual page for the rcp command.
Privilege Required
None
Related Information
UNIX manual page for rcp
IBM AFS Release Notes
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.
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.
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.
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
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
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).
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.
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
UNIX manual page for ntp
UNIX manual page for ntpd
UNIX manual page for ntpdc
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
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
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
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:
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:
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.
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.
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
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.
_ _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.
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
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
An example of an acceptable value is conn 300.
An example of an acceptable value is disk 5000.
An example is disk 90%.
Example of a legal value: fetch 6000000
Example of an acceptable value: store 200000
Example of an acceptable value: ws 65
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:
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
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:
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
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
IBM AFS Quick Beginnings
IBM AFS Administration Guide
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
Output
The output lists one token for each cell in which the user is authenticated. The output indicates the
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
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
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
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
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
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.
I am sync site forever (1 server)
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:
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
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:
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
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
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
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:
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
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.
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
Note: | This flag is not available in the international edition of AFS. |
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.
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
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
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).
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
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
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
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:
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.
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
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
Corresponding variable in the template file: $USER.
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.
Corresponding variable in the template file: none.
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 variable in the template file: $PWEXPIRES.
Corresponding variable in the template file: $SERVER.
/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.
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 fs mkmount reference page.
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.
Corresponding variable in the template file: $UID.
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.
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:
See the chapter on uss in the IBM AFS Administration Guide for further explanation.
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
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
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
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
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).
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
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.
Options
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.
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
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
Output
The online help entry for each uss command consists of the following two or three lines:
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
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
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 VLDB.
Privilege Required
The issuer must be logged in as the local superuser root.
Related Information
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
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
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
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
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
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
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
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
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:
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.
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.
Use this flag only when issuing a command on a server machine; client machines do not usually have a /usr/afs/etc/KeyFile file. The issuer of a command that includes this flag must be logged on to the server machine as the local superuser root. The flag is useful for commands invoked by an unattended application program, such as a process controlled by the UNIX cron utility or by a cron entry in the machine's /usr/afs/local/BosConfig file. It is also useful if an administrator is unable to authenticate to AFS but is logged in as the local superuser root.
Do not combine the -cell and -localauth options. A command on which the -localauth flag is included always runs in the local cell (as defined in the server machine's local /usr/afs/etc/ThisCell file), whereas a command on which the -cell argument is included runs in the specified foreign cell. Also, do not combine the -localauth and -noauth flags.
/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.
The -fromserver and -toserver arguments to the vos move command also accept these name formats.
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
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
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
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
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
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
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
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
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 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:
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:
-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.
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
This argument can be combined with any combination of the -prefix, -partition, -exclude, and -xprefix options.
This argument can be combined with any combination of the -prefix, -server, -exclude, and -xprefix options.
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:
Would have backed up volumes which are prefixed with string [orstring] . .
Would have backed up volumes which are not prefixed with string [norstring] . .
Would have backed up volumes which are prefixed with string [orstring] \ removing those which are prefixed with x_string [orx_string] . .
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
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
UNIX manual page for regexp(5)
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
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
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:
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
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
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
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:
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
Combine this argument with the -prefix argument, the -partition argument, or both.
Combine this argument with the -prefix argument, the -server argument, or both.
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
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
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
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
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.
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
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
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.
When the -extended flag is included, two tables appear next:
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 ****
Following a blank line, information from the VLDB entry appears. Each item in this list corresponds to a separate line in the output:
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
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
Output
The online help entry for each vos command consists of the following two or three lines:
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
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
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
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
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
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:
Options
This argument can be combined with the -partition argument, the -locked flag, or both.
This argument can be combined with the -server argument, the -locked flag, or both.
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:
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
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:
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
This argument can be combined with the -partition argument, as well as the -fast, -long, or -extended flag.
Output
The output is ordered alphabetically by volume name and by default provides the following information on a single line for each volume:
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 ****
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. These lines do not appear if the -quiet flag is used.
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:
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:
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
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
Examples
The following command locks the VLDB entry for user.terry.
% vos lock user.terry
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
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:
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
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
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
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.
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
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.
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:
By default, the Volume Server determines automatically whether or not it needs to create a new ReleaseClone:
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.
Options
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
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
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.
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
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.
Note: | If the -server and -partition arguments are omitted, the -id switch must be provided. |
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
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
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
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
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
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
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
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
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.
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:
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
This argument is mandatory if the -file argument is not provided.
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
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
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
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:
A fourth line can appear during certain transactions, and includes the following fields:
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
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.
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 file server machines.
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
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
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
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
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
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
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
Examples
The following example unlocks the VLDB entry for the volume user.terry.
% vos unlock user.terry
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
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 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
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
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
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
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
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
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.
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
There are three acceptable values:
Related Information
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
There are three acceptable values:
Related Information
Version 3.6
Document Number SC09-4560-00
CT6Q7NA
First Edition (April 2000)
This edition applies to:
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.
Installing the First AFS Machine
Installing Additional Server Machines
Installing Additional Client Machines
Appendix A. Building AFS from Source Code
This section describes the purpose, organization, and conventions of this document.
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.
See The Procedures Described in this Guide.
See The Procedures Described in this Guide and How to Continue.
The AFS documentation set also includes the following documents.
IBM AFS Administration Guide
This guide describes the concepts and procedures that a system administrator must know to manage an AFS cell. It assumes familiarity with UNIX, but requires no previous knowledge of AFS.
The first chapters of the IBM AFS Administration Guide present basic concepts and guidelines. Understanding them is crucial to successful administration of an AFS cell. The remaining chapters in the guide provide step-by-step instructions for specific administrative tasks, along with discussions of the concepts important to that particular task.
IBM AFS Administration Reference
This reference manual details the syntax and effect of each AFS command. It is intended for the experienced AFS administrator, programmer, or user.
The IBM AFS Administration Reference lists AFS files and commands in alphabetical order. The reference page for each command specifies its syntax, including the acceptable aliases and abbreviations. It then describes the command's function, arguments, and output if any. Examples and a list of related commands are provided, as are warnings where appropriate.
This manual complements the IBM AFS Administration Guide: it does not include procedural information, but describes commands in more detail than the IBM AFS Administration Guide.
IBM AFS User Guide
This guide presents the basic concepts and procedures necessary for using AFS effectively. It assumes that the reader has some experience with UNIX, but does not require familiarity with networking or AFS.
The guide explains how to perform basic functions, including authenticating, changing a password, protecting AFS data, creating groups, and troubleshooting. It provides illustrative examples for each function and describes some of the differences between the UNIX file system and AFS.
IBM AFS Release Notes
This document provides information specific to each release of AFS, such as a list of new features and commands, a list of requirements and limitations, and instructions for upgrading server and client machines.
This document uses the following typographical conventions:
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.
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 the appendix to the IBM AFS Administration Guide.
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.
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).
You must perform the following basic procedures to start using AFS.
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.
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:
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.
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.
See Installing an Additional File Server Machine.
See Installing Database Server Functionality and Removing Database Server Functionality.
See Installing Additional Client Machines.
See Appendix A, Building AFS from Source Code.
To develop the best understanding of the overall scope of an installation procedure, read through the entire chapter or section that describes it before performing any actions.
In addition, familiarity with some basic AFS concepts can make the installation more efficient, because you understand better the purpose of the steps. The following is a prioritized list of material to read before installing the first AFS machine. At minimum, read the first chapter of the IBM AFS Administration Guide. Then continue your reading in the indicated order, as extensively as you can. It is more important at this point to read the conceptual material in each section than the instructions.
Selected Topics in the IBM AFS Administration Guide
More Selected Topics in the IBM AFS Administration Guide
You must comply with the following requirements to install AFS successfully.
Log into the machine you are installing as the local superuser root. When instructed, also authenticate with AFS as the administrative user admin.
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.
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.
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.
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.
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.
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.
The instructions in this chapter assume that you meet the following requirements.
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.
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:
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:
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.
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
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:
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.
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. |
To continue, proceed to the appropriate section:
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.
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.
# cd /cdrom/rs_aix42/root.client/usr/vice/etc
# cp -rp dkload /usr/vice/etc # cp -p rc.afs /etc/rc.afs
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
# /etc/rc.afs
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:
# mkdir /vicepxx
Also configure the partitions so that they are mounted automatically at each reboot. For more information, refer to the AIX documentation.
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.
# cd /sbin/helpers # mv v3fshelper v3fshelper.noafs # cp -p /cdrom/rs_aix42/root.server/etc/v3fshelper v3fshelper
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.
# 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
registry = DCE
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])"
root: registry = files
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
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
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.
Use the following instructions to build AFS modifications into the kernel on a Digital UNIX system.
# cd /usr/sys/conf # cp machine_name AFS
. . . . options UFS options NFS options AFS . . . .
. . . . . . OPTIONS/nfs optional nfs OPTIONS/afs optional afs OPTIONS/nfs_server optional nfs_server . . . . . .
. . . . . . . . # 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 #
. . . . #include <afs.h> #if defined(AFS) && AFS extern struct vfsops afs_vfsops; #endif . . . .
. . . . . . &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 */
# cd /cdrom/alpha_dux40/root.client
# cp usr/vice/etc/afs.rc /sbin/init.d/afs
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
# doconfig -c AFS
# mv /vmunix /vmunix_noafs # cp /sys/AFS/vmunix /vmunix
# cd / # shutdown -r now login: root Password: root_password
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.
# mkdir /vicepxx
/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
# newfs -v /dev/disk
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 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.
# cd /cdrom/alpha_dux40/root.server/etc # cp vfsck /sbin/vfsck # cp vfsck /usr/sbin/vfsck
# 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
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.
# cd /cdrom/alpha_dux40/lib/afs
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
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.
Use the following instructions to build AFS modifications into the kernel on an HP-UX system.
# cp /stand/vmunix /stand/vmunix.noafs # cp /stand/system /stand/system.noafs
# cd /cdrom/hp_ux110/root.client
# cp usr/vice/etc/afs.rc /sbin/init.d/afs
# cp usr/vice/etc/afs.driver /usr/conf/master.d/afs
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
# sam -display local_hostname:0
login: root Password: root_password
# cd /stand/build # mk_kernel
# mv /stand/build/vmunix_test /stand/vmunix # cd / # shutdown -r now login: root Password: root_password
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.
# mkdir /vicepxx
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 HP-UX systems, there are several configuration files to install in addition to the AFS-modified fsck program (the vfsck binary).
format_revision 1 fsck 0 m,P,p,d,f,b:c:y,n,Y,N,q,
# mkdir /sbin/fs/afs # cd /sbin/fs/afs
# cp -p /cdrom/hp_ux110/root.server/etc/* .
# 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
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.
Perform the following steps to enable AFS login.
# cd /usr/lib/security
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
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
To incorporate AFS into the kernel on IRIX systems, choose one of two methods:
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:
# cd /cdrom/sgi_65/root.client
# cp -p usr/vice/etc/afs.rc /etc/init.d/afs
# uname -m
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.
# mkdir /usr/vice/etc/sgiload
(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
# /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
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
Use the following instructions to build AFS modifications into the kernel on an IRIX system.
# cp -p bin/afs.sm /var/sysgen/system # cp -p bin/afs /var/sysgen/master.d
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
# /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
# cp /unix /unix_noafs # autoconfig
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
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.
AFS supports use of both EFS and XFS partitions for housing AFS volumes. SGI encourages use of XFS partitions.
# mkdir /vicepxx
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
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
# /usr/afs/bin/xfs_size_check
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.
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.
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.
# cd /cdrom/i386_linux22/root.client/usr/vice/etc
# cp -rp modload /usr/vice/etc
# cp -p afs.rc /etc/rc.d/init.d/afs
# /etc/rc.d/init.d/afs start
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.
# mkdir /vicepxx
/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
# mkfs -v /dev/disk
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.
The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three attributes.
Perform the following steps to enable AFS login.
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
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
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
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.
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.
# cd /cdrom/sun4x_56/root.client/usr/vice/etc
# cp -p afs.rc /etc/init.d/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
# /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
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.
# mkdir /usr/lib/fs/afs # cd /usr/lib/fs/afs
# cp /cdrom/sun4x_56/root.server/etc/vfsck fsck
# 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
afs AFS Utilities
case "$2" in ufs) foptions="-o p" ;; afs) foptions="-o p" ;; s5) foptions="-y -t /var/tmp/tmp$$ -D" ;; *) foptions="-y" ;;
# 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
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.
# mkdir /vicepxx
/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
# newfs -v /dev/rdsk/disk
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.
Perform the following steps to enable AFS login.
# cd /usr/lib/security
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
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
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 */
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.
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.
# cd /cdrom/sysname/root.server/usr/afs # cp -rp * /usr/afs
# /usr/afs/bin/bosserver -noauth &
# 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
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:
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). |
# 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.
# ./bos listhosts <machine name> -noauth Cell name is cell_name Host 1 is machine_name
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:
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.
# ./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.
# ./bos create <machine name> buserver simple /usr/afs/bin/buserver \ -cell <cell name> -noauth
# ./bos create <machine name> ptserver simple /usr/afs/bin/ptserver \ -cell <cell name> -noauth
# ./bos create <machine name> vlserver simple /usr/afs/bin/vlserver \ -cell <cell name> -noauth
Now initialize the cell's security mechanisms. Begin by creating the following two initial entries in the Authentication Database:
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.
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.
# kas -cell <cell name> -noauth ka>
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
ka> examine afs User data for afs key (0) cksum is checksum . . .
ka> setfields admin -flags admin ka> examine admin User data for admin (ADMIN) . . .
ka> quit
# ./bos adduser <machine name> admin -cell <cell name> -noauth
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
# ./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
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
# ./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
# ./bos restart <machine name> -all -cell <cell name> -noauth
Start the fs process, which consists of the File Server, Volume Server, and Salvager (fileserver, volserver and salvager processes).
# ./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
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.
# ./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.
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.
# ./bos create <machine name> upserver simple \ "/usr/afs/bin/upserver -crypt /usr/afs/etc \ -clear /usr/afs/bin" -cell <cell name> -noauth
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.
# ./bos create <machine name> runntp simple \ "/usr/afs/bin/runntp <host>+" -cell <cell name> -noauth
# ./bos create <machine name> runntp simple \ "/usr/afs/bin/runntp -localclock" -cell <cell name> -noauth
# ./bos create <machine name> runntp simple \ "/usr/afs/bin/runntp -localclock <host>+" \ -cell <cell name> -noauth
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:
Before installing and configuring the AFS client, copy the necessary files from the AFS CD-ROM 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
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:
# cd /usr/vice/etc # rm ThisCell
# cp /usr/afs/etc/ThisCell ThisCell
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.
# rm CellServDB # mv CellServDB.sample CellServDB
# 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.
>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).
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 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
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 values you define must meet the following requirements.
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.
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.
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:
# mkdir /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
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
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 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
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:
# mkdir /afs
afs 4 none none
# cp /usr/vice/etc/afs.conf /etc/sysconfig/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.
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:
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:
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.
# /usr/afs/bin/bos shutdown <machine name> -wait
# ps appropriate_ps_options | grep bosserver # kill bosserver_PID
On AIX systems:
# cd / # shutdown -r now login: root Password: root_password
# /etc/rc.afs
On Digital UNIX systems:
# /sbin/init.d/afs start
On HP-UX systems:
# /sbin/init.d/afs start
On IRIX systems:
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
# /etc/chkconfig -f afsserver on # /etc/chkconfig -f afsclient on
# /etc/init.d/afs start
On Linux systems:
# cd / # shutdown -r now login: root Password: root_password
# /etc/rc.d/init.d/afs start
On Solaris systems:
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
# /etc/init.d/afs start
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
# /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--
# /usr/afs/bin/bos status <machine name>
# cd / # /usr/afs/bin/fs checkvolumes
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:
rcafs:2:wait:/etc/rc.afs > /dev/console 2>&1 # Start AFS services
# cd /usr/vice/etc # rm rc.afs # ln -s /etc/rc.afs
# cd /sbin/init.d # ln -s ../init.d/afs /sbin/rc3.d/S67afs # ln -s ../init.d/afs /sbin/rc0.d/K66afs
# cd /usr/vice/etc # rm afs.rc # ln -s /sbin/init.d/afs afs.rc
# cd /sbin/init.d # ln -s ../init.d/afs /sbin/rc2.d/S460afs # ln -s ../init.d/afs /sbin/rc2.d/K800afs
# cd /usr/vice/etc # rm afs.rc # ln -s /sbin/init.d/afs afs.rc
# cd /etc/init.d # ln -s ../init.d/afs /etc/rc2.d/S35afs # ln -s ../init.d/afs /etc/rc0.d/K35afs
# cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc
# /sbin/chkconfig --add afs
# 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
# cd /etc/init.d # ln -s ../init.d/afs /etc/rc3.d/S99afs # ln -s ../init.d/afs /etc/rc0.d/K66afs
# cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc
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.
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
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
# cd /afs # ln -s full_cellname short_cellname
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
# ./vos addsite <machine name> <partition name> root.afs # ./vos addsite <machine name> <partition name> root.cell
# ./fs examine /afs # ./fs examine /afs/cellname
# ./vos release root.afs # ./vos release root.cell
# ./fs checkvolumes # ./fs examine /afs # ./fs examine /afs/cellname
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.
# vos create <machine name> <partition name> sysname # vos create <machine name> <partition name> sysname.usr # vos create <machine name> <partition name> sysname.usr.afsws
# 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
# cd /afs/.cellname/sysname # fs setacl -dir . usr usr/afsws -acl system:anyuser rl
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
# 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 .
# cd /afs/.cellname/sysname/usr/afsws # fs setacl -dir etc include lib -acl system:authuser rl \ system:anyuser none
# ln -s /afs/cellname/@sys/usr/afsws /usr/afsws
The AFS distribution includes the following documents:
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.
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
# fs mkmount -dir /afs/.cellname/afsdoc -vol afsdoc # vos release root.cell # fs checkvolumes
# cd /afs/.cellname/afsdoc # fs setacl . system:anyuser rl
# 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).
# 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.
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:
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 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 |
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.
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
For each cell that does not already have an entry, complete the following instructions:
# /usr/afs/bin/fs newcell <foreign_cell> <dbserver1> \ [<dbserver2>] [<dbserver3>]
# mkdir common # mkdir common/etc # cp /usr/vice/etc/CellServDB common/etc # /usr/afs/bin/vos release root.cell
# ls /afs/foreign_cell
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.
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:
Following are suggestions for managing AFS administrative privilege:
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 |
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.
# cd /usr/vice/etc # rm * # rm -rf C
# ln -s /usr/afs/etc/ThisCell ThisCell # ln -s /usr/afs/etc/CellServDB CellServDB
# /etc/chkconfig -f afsclient off
# cd / # shutdown appropriate_options
Instructions for the following procedures appear in the indicated section of this chapter.
The instructions make the following assumptions.
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:
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:
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.
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.
To continue, proceed to the section for this system type:
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.
# cd /cdrom/rs_aix42/root.client/usr/vice/etc
# cp -rp dkload /usr/vice/etc # cp -p rc.afs /etc/rc.afs
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
# /etc/rc.afs
# mkdir /vicepxx
Also configure the partitions so that they are mounted automatically at each reboot. For more information, refer to the AIX documentation.
# cd /sbin/helpers # mv v3fshelper v3fshelper.noafs # cp -p /cdrom/rs_aix42/root.server/etc/v3fshelper v3fshelper
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.
# cd /usr/sys/conf # cp machine_name AFS
. . . . options UFS options NFS options AFS . . . .
. . . . . . OPTIONS/nfs optional nfs OPTIONS/afs optional afs OPTIONS/nfs_server optional nfs_server . . . . . .
. . . . . . . . # 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 #
. . . . #include <afs.h> #if defined(AFS) && AFS extern struct vfsops afs_vfsops; #endif . . . .
. . . . . . &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 */
# cd /cdrom/alpha_dux40/root.client
# cp usr/vice/etc/afs.rc /sbin/init.d/afs
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
# doconfig -c AFS
# mv /vmunix /vmunix_noafs # cp /sys/AFS/vmunix /vmunix
# cd / # shutdown -r now login: root Password: root_password
# mkdir /vicepxx
/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
# newfs -v /dev/disk
# cd /cdrom/alpha_dux40/root.server/etc # cp vfsck /sbin/vfsck # cp vfsck /usr/sbin/vfsck
# 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
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.
# cp /stand/vmunix /stand/vmunix.noafs # cp /stand/system /stand/system.noafs
# cd /cdrom/hp_ux110/root.client
# cp usr/vice/etc/afs.rc /sbin/init.d/afs
# cp usr/vice/etc/afs.driver /usr/conf/master.d/afs
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
# sam -display local_hostname:0
login: root Password: root_password
# cd /stand/build # mk_kernel
# mv /stand/build/vmunix_test /stand/vmunix # cd / # shutdown -r now login: root Password: root_password
# mkdir /vicepxx
format_revision 1 fsck 0 m,P,p,d,f,b:c:y,n,Y,N,q,
# mkdir /sbin/fs/afs # cd /sbin/fs/afs
# cp -p /cdrom/hp_ux110/root.server/etc/* .
# 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
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.
# cd /cdrom/sgi_65/root.client
# cp -p usr/vice/etc/afs.rc /etc/init.d/afs
# uname -m
# mkdir /usr/vice/etc/sgiload
(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
# /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
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
# cp -p bin/afs.sm /var/sysgen/system # cp -p bin/afs /var/sysgen/master.d
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
# /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
# cp /unix /unix_noafs # autoconfig
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
# mkdir /vicepxx
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
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
# /usr/afs/bin/xfs_size_check
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.
# cd /cdrom/i386_linux22/root.client/usr/vice/etc
# cp -rp modload /usr/vice/etc
# cp -p afs.rc /etc/rc.d/init.d/afs
# /etc/rc.d/init.d/afs start
# mkdir /vicepxx
/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
# mkfs -v /dev/disk
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.
# cd /cdrom/sun4x_56/root.client/usr/vice/etc
# cp -p afs.rc /etc/init.d/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
# /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
# mkdir /usr/lib/fs/afs # cd /usr/lib/fs/afs
# cp /cdrom/sun4x_56/root.server/etc/vfsck fsck
# 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
afs AFS Utilities
case "$2" in ufs) foptions="-o p" ;; afs) foptions="-o p" ;; s5) foptions="-y -t /var/tmp/tmp$$ -D" ;; *) foptions="-y" ;;
# 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
# mkdir /vicepxx
/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
# newfs -v /dev/rdsk/disk
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.
# cd /cdrom/sysname/root.server/usr/afs # cp -rp * /usr/afs
# cd /usr/afs/bin # ./bosserver -noauth &
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
# ./bos create <machine name> upserver simple \ "/usr/afs/bin/upserver -clear /usr/afs/bin" \ -cell <cell name> -noauth
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
# ./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. |
# ./bos create <machine name> fs fs \ /usr/afs/bin/fileserver /usr/afs/bin/volserver \ /usr/afs/bin/salvager -cell <cell name> -noauth
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.
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
# cd /usr/vice/etc # rm ThisCell # cp /usr/afs/etc/ThisCell ThisCell
# rm CellServDB
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
# mkdir /afs
afs 4 none none
# cp /usr/vice/etc/afs.conf /etc/sysconfig/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.
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.
# /usr/afs/bin/bos shutdown <machine name> -wait
# ps appropriate_ps_options | grep bosserver # kill bosserver_PID
On AIX systems:
# cd / # shutdown -r now login: root Password: root_password
# /etc/rc.afs
rcafs:2:wait:/etc/rc.afs > /dev/console 2>&1 # Start AFS services
# cd /usr/vice/etc # rm rc.afs # ln -s /etc/rc.afs
On Digital UNIX systems:
# /sbin/init.d/afs start
# cd /sbin/init.d # ln -s ../init.d/afs /sbin/rc3.d/S67afs # ln -s ../init.d/afs /sbin/rc0.d/K66afs
# cd /usr/vice/etc # rm afs.rc # ln -s /sbin/init.d/afs afs.rc
On HP-UX systems:
# /sbin/init.d/afs start
# cd /sbin/init.d # ln -s ../init.d/afs /sbin/rc2.d/S460afs # ln -s ../init.d/afs /sbin/rc2.d/K800afs
# cd /usr/vice/etc # rm afs.rc # ln -s /sbin/init.d/afs afs.rc
On IRIX systems:
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
# /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
# /etc/init.d/afs start
# cd /etc/init.d # ln -s ../init.d/afs /etc/rc2.d/S35afs # ln -s ../init.d/afs /etc/rc0.d/K35afs
# cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc
On Linux systems:
# cd / # shutdown -r now login: root Password: root_password
# /etc/rc.d/init.d/afs start
# /sbin/chkconfig --add afs
# 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
On Solaris systems:
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
# /etc/init.d/afs start
# cd /etc/init.d # ln -s ../init.d/afs /etc/rc3.d/S99afs # ln -s ../init.d/afs /etc/rc0.d/K66afs
# cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc
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.
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.
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.
To install a database server machine, perform the following procedures.
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. |
% klog admin_user Password: admin_password
% cp /usr/afsws/bin/bos /tmp
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. |
% bos listhosts <machine name>
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.
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.
% bos create <machine name> kaserver simple /usr/afs/bin/kaserver
% bos create <machine name> buserver simple /usr/afs/bin/buserver
% bos create <machine name> ptserver simple /usr/afs/bin/ptserver
% bos create <machine name> vlserver simple /usr/afs/bin/vlserver
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:
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 machine functionality is nearly the reverse of installing it.
To decommission a database server machine, perform the following procedures.
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. |
% klog admin_user Password: admin_password
% cp /usr/afsws/bin/bos /tmp
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.
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.
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.
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.
% bos listhosts <machine name>
% bos stop <machine name> kaserver buserver ptserver vlserver
% bos delete <machine name> kaserver buserver ptserver vlserver
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:
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.
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
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.
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.
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 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.
# cd /cdrom/rs_aix42/root.client/usr/vice/etc
# cp -rp dkload /usr/vice/etc # cp -p rc.afs /etc/rc.afs
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
# /etc/rc.afs
Now incorporate AFS into the AIX secondary authentication system.
# 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
registry = DCE
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])"
root: registry = files
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
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
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.
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.
# cd /usr/sys/conf # cp machine_name AFS
. . . . options UFS options NFS options AFS . . . .
. . . . . . OPTIONS/nfs optional nfs OPTIONS/afs optional afs OPTIONS/nfs_server optional nfs_server . . . . . .
. . . . . . . . # 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 #
. . . . #include <afs.h> #if defined(AFS) && AFS extern struct vfsops afs_vfsops; #endif . . . .
. . . . . . &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 */
# cd /cdrom/alpha_dux40/root.client
# cp usr/vice/etc/afs.rc /sbin/init.d/afs
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
# doconfig -c AFS
# mv /vmunix /vmunix_noafs # cp /sys/AFS/vmunix /vmunix
# cd / # shutdown -r now login: root Password: root_password
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.
# cd /cdrom/alpha_dux40/lib/afs
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
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.
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.
# cp /stand/vmunix /stand/vmunix.noafs # cp /stand/system /stand/system.noafs
# cd /cdrom/hp_ux110/root.client
# cp usr/vice/etc/afs.rc /sbin/init.d/afs
# cp usr/vice/etc/afs.driver /usr/conf/master.d/afs
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
# sam -display local_hostname:0
login: root Password: root_password
# cd /stand/build # mk_kernel
# mv /stand/build/vmunix_test /stand/vmunix # cd / # shutdown -r now login: root Password: root_password
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.
Perform the following steps to enable AFS login.
# cd /usr/lib/security
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
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
In this section you incorporate AFS into the IRIX kernel, choosing one of two methods:
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:
# cd /cdrom/sgi_65/root.client
# cp -p usr/vice/etc/afs.rc /etc/init.d/afs
# uname -m
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 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.
# mkdir /usr/vice/etc/sgiload
(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
# /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
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
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.
# cp -p bin/afs.sm /var/sysgen/system # cp -p bin/afs /var/sysgen/master.d
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
# /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
# cp /unix /unix_noafs # autoconfig
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
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 Loading and Creating Client Files.
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.
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 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.
# cd /cdrom/i386_linux22/root.client/usr/vice/etc
# cp -rp modload /usr/vice/etc
# cp -p afs.rc /etc/rc.d/init.d/afs
# /etc/rc.d/init.d/afs start
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.
The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three attributes.
Perform the following steps to enable AFS login.
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
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
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
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.
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 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.
# cd /cdrom/sun4x_56/root.client/usr/vice/etc
# cp -p afs.rc /etc/init.d/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
# /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
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.
Perform the following steps to enable AFS login.
# cd /usr/lib/security
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
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
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 */
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.
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. Among other functions, this file determines the following:
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.
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
# echo "cellname" > /usr/vice/etc/ThisCell
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 values you define must meet the following requirements.
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.
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.
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:
# mkdir /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
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
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 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
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:
# mkdir /afs
afs 4 none none
# cp /usr/vice/etc/afs.conf /etc/sysconfig/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.
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:
# cd / # shutdown -r now login: root Password: root_password
# /etc/rc.afs
rcafs:2:wait:/etc/rc.afs > /dev/console 2>&1 # Start AFS services
# cd /usr/vice/etc # rm rc.afs # ln -s /etc/rc.afs
# /sbin/init.d/afs start
# cd /sbin/init.d # ln -s ../init.d/afs /sbin/rc3.d/S67afs # ln -s ../init.d/afs /sbin/rc0.d/K66afs
# cd /usr/vice/etc # rm afs.rc # ln -s /sbin/init.d/afs afs.rc
# /sbin/init.d/afs start
# cd /sbin/init.d # ln -s ../init.d/afs /sbin/rc2.d/S460afs # ln -s ../init.d/afs /sbin/rc2.d/K800afs
# cd /usr/vice/etc # rm afs.rc # ln -s /sbin/init.d/afs afs.rc
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
# /etc/chkconfig -f afsclient on
# /etc/init.d/afs start
# cd /etc/init.d # ln -s ../init.d/afs /etc/rc2.d/S35afs # ln -s ../init.d/afs /etc/rc0.d/K35afs
# cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc
# cd / # shutdown -r now login: root Password: root_password
# /etc/rc.d/init.d/afs start
# /sbin/chkconfig --add afs
# 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
# cd / # shutdown -i6 -g0 -y login: root Password: root_password
# /etc/init.d/afs start
# cd /etc/init.d # ln -s ../init.d/afs /etc/rc3.d/S99afs # ln -s ../init.d/afs /etc/rc0.d/K66afs
# cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc
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 .
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.
# ln -s /afs/cellname/@sys/usr/afsws /usr/afsws
# 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.
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:
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.
Perform the following steps to create a volume for housing AFS binaries.
# cd /cdrom/new_sysname/root.server/usr/afs/bin # cp -p klog /tmp # cp -p fs /tmp # cp -p vos /tmp
# klog admin Password: admin_password
# vos create <machine name> <partition name> sysname # vos create <machine name> <partition name> sysname.usr # vos create <machine name> <partition name> sysname.usr.afsws
# 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
# cd /afs/.cellname/sysname # fs setacl -dir . usr usr/afsws -acl system:anyuser rl
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
# 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 .
# cd /afs/.cellname/sysname/usr/afsws # fs setacl -dir etc include lib -acl system:authuser rl \ system:anyuser none
# ln -s /afs/cellname/@sys/usr/afsws /usr/afsws
# 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.
# cd /tmp # rm klog fs vos
This chapter describes how to build AFS from source code.
Working on an AFS client machine, perform these steps to load the AFS source tree from the AFS Source Distribution.
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
# cd /cdrom/src # cp -rp * /afs/.cellname/afs/src
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.
# 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
# cd sysname # mkdir dest # mkdir dest/bin # mkdir obj
# 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
# cd /afs/.cellname/afs/sysname # ln -s full_path_of_alternate_directory dest
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
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
Version 3.6
Document Number SC09-4564-00
CT6Q8NA
First Edition (April 2000)
This edition applies to:
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.
© Copyright International Business Machines Corporation 1999. All rights reserved.
IBM AFS for Windows Quick Beginnings
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.
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.
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.
This document has the following organization:
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, version 3.6 includes the following components:
The AFS Server runs AFS server processes and includes the AFS Server Configuration Wizard to facilitate setup.
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.
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 provides access to the AFS filespace via an AFS Light Gateway machine, enabling users to manage files and directories in AFS.
AFS Supplemental Documentation provides additional AFS system administration information and includes the following documents: IBM AFS Administration Guide and IBM AFS Administration Reference.
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. |
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.
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.
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.
Installation of AFS for Windows is complete.
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.
Installing the AFS Client for Windows NT makes the following changes to your system:
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.
Installing AFS Light for Windows 95 and Windows 98 makes the following changes to your system:
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.
Installing the AFS Server for Windows NT makes the following changes to your system:
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.
Installing the AFS Control Center for Windows NT makes the following changes to your system:
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.
Installing the AFS Supplemental Documentation makes the following changes to your system:
This section describes the documentation that is provided with AFS for Windows and details the procedures for accessing this documentation.
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.
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.
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.
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.
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. |
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 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.
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.
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.
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.
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. |
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.
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.
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:
The following constraints apply to the form of an internet domain name that can be used as the name of an AFS cell:
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.
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. |
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.
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.
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: | If the Backup Server is configured on any Database Server in the cell, it must be configured on all Database Servers in the cell. |
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.
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.
The root AFS volumes are two volumes that every AFS cell must include in its file system. They are named:
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.
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.
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. |
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 configure the AFS Server into an existing AFS cell:
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.
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.
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. |
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.
The root AFS volumes are two volumes that every AFS cell must include in its file system. They are named:
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. |
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. |
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.)
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. |
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.
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. |
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.
The AFS Control Center is now configured.
This section outlines uninstallation prerequisites, provides instructions for uninstalling AFS for Windows, and lists the changes that the uninstallation process makes to your system.
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.
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:
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.
Uninstalling the AFS Client makes the following changes to your system:
Note: | The directories are not removed if they contain any files other than those installed by the AFS for Windows setup program. |
Uninstalling AFS Light makes the following changes to your system:
Note: | The directories are not removed if they contain any files other than those installed by the AFS for Windows setup program. |
Uninstalling the AFS Server makes the following changes to your system:
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. |
Uninstalling the AFS Control Center makes the following changes to your system:
Note: | These directories are not removed if they contain any files other than those installed by the AFS for Windows setup program. |
Uninstalling the AFS supplemental documentation makes the following changes to your system:
Note: | These directories are not removed if they contain any files other than those installed by the AFS for Windows setup program. |
Version 3.6
Document Number GC09-4558-00
0000000
First Edition (April 2000)
This edition applies to:
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.
This section describes the purpose, organization, and conventions used in this document.
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.
This document has the following sections:
The following documents are also included in the AFS documentation set.
IBM AFS Administration Guide
This guide describes the concepts and procedures that a system administrator must know to manage an AFS cell. It assumes familiarity with UNIX, but requires no previous knowledge of AFS.
The first chapters of the IBM AFS Administration Guide present basic concepts and guidelines. Understanding them is crucial to successful administration of an AFS cell. The remaining chapters in the guide provide step-by-step instructions for specific administrative tasks, along with discussions of the concepts important to that particular task.
IBM AFS Administration Reference
This reference manual details the syntax and effect of each AFS command. It is intended for the experienced AFS administrator, programmer, or user.
The IBM AFS Administration Reference lists AFS files and commands in alphabetical order. The reference page for each command specifies its syntax, including the acceptable aliases and abbreviations. It then describes the command's function, arguments, and output if any. Examples and a list of related commands are provided, as are warnings where appropriate.
This manual complements the IBM AFS Administration Guide: it does not include procedural information, but describes commands in more detail than the IBM AFS Administration Guide.
IBM AFS Quick Beginnings
This guide provides instructions for installing AFS server and client machines. It is assumed that the installer is an experienced UNIX (R) system administrator.
For predictable performance, machines must be installed and configured in accordance with the instructions in this guide.
IBM AFS User Guide
This guide presents the basic concepts and procedures necessary for using AFS effectively. It assumes that the reader has some experience with UNIX, but does not require familiarity with networking or AFS.
The guide explains how to perform basic functions, including authenticating, changing a password, protecting AFS data, creating groups, and troubleshooting. It provides illustrative examples for each function and describes some of the differences between the UNIX file system and AFS.
This document uses the following typographical conventions:
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.
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.
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. |
AFS 3.6 includes the following new features.
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.
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.
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 |
For a list of requirements for both server and client machines, see the chapter titled Installation Overview in the IBM AFS Quick Beginnings document.
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:
Documents are provided in the following formats:
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:
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
% 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.
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:
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.
AFS supports up to 32 addresses on a multihomed client machine. Do not configure more interfaces.
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.
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.
AFS supports a maximum file size of 2 GB.
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.
AFS supports a maximum disk cache size of 1 GB. In AFS version 3.1 and earlier, the limit is 700 MB.
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.
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).
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.
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).
There is a single edition of AFS 3.6 for both North American and international customers. For details, see Summary of New Features.
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.
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.
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.
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.
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.
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 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::
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.
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
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.
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:
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.
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.
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.
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.
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.
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.
The AIX secondary authentication system does not support setting the PASSWORD_EXPIRES environment variable during login.
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.
You can only change the HOME directory on the name server.
You can only change the User INFORMATION on the name server.
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.
AFS does not support use of Digital UNIX machines as NFS/AFS Translator machines.
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.
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:
options RT_PREEMPT_OPT
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 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.
AFS does not support use of HP-UX 11.0 machines as NFS/AFS Translator machines.
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.
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.
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.
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.
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.
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 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 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
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
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>.
For correct AFS performance, the operating system must use the C library called libc6 (or glibc2), rather than libc5 (glibc1).
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:
AFS does not support the use of Linux machines as NFS/AFS Translator machines.
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.
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.
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.
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:
For more details, see Documentation Notes.
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.
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.
Use the following command to determine which version of CDE you are running:
% pkginfo -l SUNWdtdte
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.
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.
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:
Edit the stanzas 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
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
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
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).
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).
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:
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.
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.
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.
AFS 3.6 adds the following new options and functionality to existing commands and files.
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.
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.)
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.
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.
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.
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.
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 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.
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:
The AFS 3.6 version of the following commands and configuration files include new options or instructions to support backup to TSM.
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.)
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:
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.
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.
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.
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.
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.
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.
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.
In AFS 3.6, there is one acceptable value for the TYPE instruction in the CFG_tcid file: tsm.
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.
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:
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).
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. |
% su root Password: root_password
ftp> bin
ftp> cd storage/tivoli-storage-management-maintenance/client/v3r7
ftp> cd AIX/v371 ftp> get tivoli.tsm.client.api.aix43.32bit
ftp> cd Solaris/v371 ftp> get IP21804.tar.Z
# uncompress IP21804.tar.Z | tar xvf -
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.
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
ServerName machine_name tapeprompt no compressalways yes
# backup addhost <tape machine name> <TC port offset>
where
For more detailed descriptions of the instructions, and of other instructions you can include in the configuration file, see CFG_tcid.
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. |
You must meet the following requirements to upgrade successfully to AFS 3.6:
Use one of the following methods to obtain the AFS distribution of each system type for which you are licensed.
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.
% vos create <machine name> <partition name> sysname.3.6 -maxquota 0
% fs mkmount /afs/.cellname/temp sysname.3.6
% cd /cdrom/sysname
% cd temp_afs36_dir
% cp -rp bin /afs/.cellname/temp % cp -rp etc /afs/.cellname/temp % cp -rp include /afs/.cellname/temp % cp -rp lib /afs/.cellname/temp
% cp -rp root.client /afs/.cellname/temp
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
% vos rename sysname.3.6 sysname.usr.afsws
% fs rmmount /afs/.cellname/temp
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:
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.
% su root Password: root_password
# mkdir /usr/afs/bin.36
# cd /cdrom/sysname/root.server/usr/afs/bin
# cd temp_afs36_dir/root.server/usr/afs/bin
# cp -p * /usr/afs/bin.36
# cd /usr/afs # mv bin bin.old # mv bin.36 bin
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 do not use binary distribution machines, perform the instructions in Distributing Binaries to Server Machines on this machine.
% su root Password: root_password
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
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.
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:
In any other circumstances, you can choose to upgrade the kernel extensions later. Choose one of the following options:
# bos restart <machine name> -localauth -bosserver
# 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
% su root Password: root_password
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
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.
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:
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 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.
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
# cd usr/vice/etc # cp -rp dkload /usr/vice/etc
If the initialization file is not already in place, copy it now.
# cp -p rc.afs /etc/rc.afs
NFS=$NFS_NONE
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
rcafs:2:wait:/etc/rc.afs > /dev/console 2>&1 # Start AFS services
# cd /usr/vice/etc # rm rc.afs # ln -s /etc/rc.afs
# shutdown -r now
login: root Password: root_password
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.
# cd /usr/sys/conf # cp machine_name AFS
. . . . options UFS options NFS options AFS . . . .
. . . . . . OPTIONS/nfs optional nfs define_dynamic OPTIONS/afs optional afs define_dynamic OPTIONS/cdfs optional cdfs define_dynamic . . . . . .
. . . . . . . . # 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 #
. . . . #include <afs.h> #if defined(AFS) && AFS extern struct vfsops afs_vfsops; #endif . . . .
. . . . . . &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 */
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
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
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
# doconfig -c AFS
# mv /vmunix /vmunix_orig # cp -p /sys/AFS/vmunix /vmunix
# ln -s ../init.d/afs /sbin/rc3.d/S67afs # ln -s ../init.d/afs /sbin/rc0.d/K66afs
# cd /usr/vice/etc # rm afs.rc # ln -s /sbin/init.d/afs afs.rc
# shutdown -r now
login: root Password: root_password
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.
# cp -p /stand/vmunix /stand/vmunix.noafs # cp -p /stand/system /stand/system.noafs
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
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
# cp -p usr/vice/etc/afs.driver /usr/conf/master.d/afs
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
# ln -s ../init.d/afs /sbin/rc2.d/S460afs # ln -s ../init.d/afs /sbin/rc2.d/K800afs
# cd /usr/vice/etc # rm afs.rc # ln -s /sbin/init.d/afs afs.rc
# sam -display local_hostname:0
login: root Password: root_password
# cd /stand/build # mk_kernel
# mv /stand/build/vmunix_test /stand/vmunix # cd / # shutdown -r now login: root Password: root_password
login: root Password: root_password
To incorporate AFS into the kernel on IRIX machines, choose one of two methods:
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.
# uname -m
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
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
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.
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
# uname -m
# 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
# cp -p afs.sm /var/sysgen/system # cp -p afs /var/sysgen/master.d
# cp -p /unix /unix_orig # autoconfig
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.
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# 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 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
# ln -s ../init.d/afs /etc/rc2.d/S35afs # ln -s ../init.d/afs /etc/rc0.d/K35afs
# cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc
# shutdown -i6 -g0 -y
login: root Password: root_password
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.
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
# cd usr/vice/etc # cp -rp modload /usr/vice/etc
# 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.
# /sbin/chkconfig --add afs
# 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
# shutdown -r now
login: root Password: root_password
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.
# cd /afs/cellname/sysname/usr/afsws/root.client
# cd /cdrom/sysname/root.client
# cd temp_afs36_dir/root.client
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
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
# ln -s ../init.d/afs /etc/rc3.d/S99afs # ln -s ../init.d/afs /etc/rc0.d/K66afs
# cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc
# shutdown -i6 -g0 -y
login: root Password: root_password
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:
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
% fs mkmount -dir /afs/.cellname/afsdoc -vol afsdoc % vos release root.cell % fs checkvolumes
% cd /afs/.cellname/afsdoc % fs setacl . system:anyuser rl
# 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).
# 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.
Following are reference pages that include new information not included in IBM AFS Administration Reference.
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:
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:
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.
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 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 instruction does not apply to XBSA servers.
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
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:
If the third field in the tapeconfig file names the actual file, there is no way to recover from exhausting the space on the partition that houses the backup data file. It is not possible to change the tapeconfig file in the middle of an operation.
When writing to a backup data file, the Tape Coordinator writes data at 16 KB offsets. If a given block of data (such as the marker that signals the beginning or end of a volume) does not fill the entire 16 KB, the Tape Coordinator still skips to the next offset before writing the next block. In the output of a backup dumpinfo command issued with the -id option, the value in the Pos column is the ordinal of the 16-KB offset at which the volume data begins, and so is not generally only one higher than the position number on the previous line, as it is for dumps to tape.
The 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.
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.
The Tape Coordinator passes the following parameters to the script indicated by the MOUNT instruction, in the indicated order:
The routine invoked by the MOUNT instruction must return an exit code to the Tape Coordinator:
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 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
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.
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.
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:
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_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
Finally, the administrator writes the following executable routine in the /usr/afs/backup/stacker0.1 file referenced by the MOUNT and UNMOUNT instructions in the CFG_stacker0.1 file.
#! /bin/csh -f set devicefile = $1 set operation = $2 set tries = $3 set tapename = $4 set tapeid = $5 set exit_continue = 0 set exit_abort = 1 set exit_interactive = 2 #-------------------------------------------- if (${tries} > 1) then echo "Too many tries" exit ${exit_interactive} endif if (${operation} == "unmount") then echo "UnMount: Will leave tape in drive" exit ${exit_continue} endif if ((${operation} == "dump") |\ (${operation} == "appenddump") |\ (${operation} == "savedb")) then stackerCmd_NextTape ${devicefile} if (${status} != 0)exit${exit_interactive} echo "Will continue" exit ${exit_continue} endif if ((${operation} == "labeltape") |\ (${operation} == "readlabel")) then echo "Will continue" exit ${exit_continue} endif echo "Prompt for tape" exit ${exit_interactive}
This routine uses two of the parameters passed to it by the Backup System: tries and operation. It follows the recommended practice of prompting for a tape if the value of the tries parameter exceeds one, because that implies that the stacker is out of tapes.
For a backup dump or backup savedb operation, the routine calls the example stackerCmd_NextTape function provided by the stacker's manufacturer. Note that the final lines in the file return the exit code that prompts the operator to insert a tape; these lines are invoked when either the stacker cannot load a tape or 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
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.
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
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.
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
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:
As it initializes, the File Server constructs a list of interfaces to register, from the /usr/afs/local/NetInfo file if it exists, or from the list of interfaces configured with the operating system otherwise. The File Server then removes from the list any addresses that appear in the NetRestrict file, if it exists. The File Server records the resulting list in the /usr/afs/local/sysid file and registers the interfaces in the VLDB. The database server processes use a similar procedure when initializing, to determine which interfaces to use for communication with the peer processes on other database machines in the cell.
The NetRestrict file is in ASCII format. One IP address appears on each line, in dotted decimal format. The order of the addresses is not significant.
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
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 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.
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 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.
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
Provide either this argument, the -to (and optionally -from) argument, or the -groupid argument.
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. |
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, 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.
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. |
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.
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.
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
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
CFG_tcid
backup
backup dumpinfo
backup scantape
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
Output
If the -ndumps argument is provided, the output presents the following information in table form, with a separate line for each dump:
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:
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:
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:
If both the -id and -verbose options are provided, the output is divided into several sections:
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
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 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
The issuer must be listed in the /usr/afs/etc/UserList file on every machine where the Backup Server is running, or must be logged onto a server machine as the local superuser root if the -localauth flag is included.
Related Information
backup
backup deletedump
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
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
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.
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
The issuer must be listed in the /usr/afs/etc/UserList file on every machine where the Backup Server is running, or must be logged onto a server machine as the local superuser root if the -localauth flag is included.
Related Information
backup
butc
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.
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:
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.
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
Combine this argument with the -prefix argument, the -partition argument, or both.
Combine this argument with the -prefix argument, the -server argument, or both.
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
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 remove
vos syncserv
vos syncvldb
vos zap
Version 3.6
Document Number GC09-4561-00
First Edition (April 2000)
This edition applies to:
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.
Displaying Information about AFS
Protecting Your Directories and Files
Appendix A. Using the NFS/AFS Translator
Appendix B. AFS Command Syntax and Online Help
This section describes the purpose, organization, and conventions of this document.
This guide describes concepts and procedures for accessing information stored in the AFS filespace. It is intended for AFS users who are familiar with UNIX but not necessarily AFS.
The first chapter describes basic AFS concepts and guidelines for using it, and summarizes some of the differences between the UNIX file system and AFS. The remaining chapters explain how to perform basic AFS functions, including logging in, changing a password, listing information, protecting files, creating groups, and troubleshooting. Concepts important to a specific task or group of related tasks are presented in context, just prior to the procedures. Many examples are provided.
Instructions generally include only the commands and command options necessary for a specific task. For a complete list of AFS commands and description of all options available on every command, see the IBM AFS Administration Reference.
This document is divided into the following chapters.
An Introduction to AFS introduces the basic concepts and functions of AFS. To use AFS successfully, it is important to be familiar with the terms and concepts described in this chapter.
Using AFS describes how to use AFS's basic features: how to log in and authenticate, unlog, log out, access AFS files and directories in AFS, and change your password.
Displaying Information about AFS describes how to display information about AFS volume quota and location, file server machine status, and the foreign cells you can access.
Protecting Your Directories and Files describes how to protect your data using AFS access control lists (ACLs).
Using Groups describes how to create and manage groups.
Troubleshooting outlines step-by-step diagnostic and corrective steps for specific problems.
Appendix A, Using the NFS/AFS Translator describes how to use the NFS/AFS Translator to access the AFS filespace from an NFS client machine.
Appendix B, AFS Command Syntax and Online Help describes AFS command syntax and how to obtain online information about commands.
Appendix C, Glossary defines terms used in the IBM AFS User Guide.
Before you begin using AFS, read An Introduction to AFS. Next, follow the procedures outlined in Using AFS to get started using AFS as an authenticated user. It describes how to access files in the AFS filespace and how to end an AFS session. Consult the other chapters as you need to perform the tasks they describe.
The AFS Documentation Kit also includes the following documents:
This document uses the following typographical conventions:
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.
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, AFS Command Syntax and Online Help.
This chapter introduces basic AFS concepts and terms. It assumes that you are already familiar with standard UNIX commands, file protection, and pathname conventions.
AFS makes it easy for people to work together on the same files, no matter where the files are located. AFS users do not have to know which machine is storing a file, and administrators can move files from machine to machine without interrupting user access. Users always identify a file by the same pathname and AFS finds the correct file automatically, just as happens in the local file system on a single machine. While AFS makes file sharing easy, it does not compromise the security of the shared files. It provides a sophisticated protection scheme.
AFS uses a client/server computing model. In client/server computing, there are two types of machines. Server machines store data and perform services for client machines. Client machines perform computations for users and access data and services provided by server machines. Some machines act as both clients and servers. In most cases, you work on a client machine, accessing files stored on a file server machine.
AFS is a distributed file system which joins together the file systems of multiple file server machines, making it as easy to access files stored on a remote file server machine as files stored on the local disk. A distributed file system has two main advantages over a conventional centralized file system:
AFS hides its distributed nature, so working with AFS files looks and feels like working with files stored on your local machine, except that you can access many more files. And because AFS relies on the power of users' client machines for computation, increasing the number of AFS users does not slow AFS performance appreciably, making it a very efficient computing environment.
AFS acts as an extension of your machine's local UNIX file system. Your system administrator creates a directory on the local disk of each AFS client machine to act as a gateway to AFS. By convention, this directory is called /afs, and it functions as the root of the AFS filespace.
Just like the UNIX file system, AFS uses a hierarchical file structure (a tree). Under the /afs root directory are subdirectories created by your system administrator, including your home directory. Other directories that are at the same level of the local file system as /afs, such as /usr, /etc, or /bin, can either be located on your local disk or be links to AFS directories. Files relevant only to the local machine are usually stored on the local machine. All other files can be stored in AFS, enabling many users to share them and freeing the local machine's disk space for other uses.
Note: | You can use AFS commands only on files in the AFS filespace or the local directories that are links to the AFS filespace. |
The cell is the administrative domain in AFS. Each cell's administrators determine how client machines are configured and how much storage space is available to each user. The organization corresponding to a cell can be a company, a university department, or any defined group of users. From a hardware perspective, a cell is a grouping of client machines and server machines defined to belong to the same cell. An AFS site is a grouping of one or more related cells. For example, the cells at the ABC Corporation form a single site.
By convention, the subdirectories of the /afs directory are cellular filespaces, each of which contains subdirectories and files that belong to a single cell. For example, directories and files relevant to the ABC Corporation cell are stored in the subdirectory /afs/abc.com.
While each cell organizes and maintains its own filespace, it can also connect with the filespace of other AFS cells. The result is a huge filespace that enables file sharing within and across cells.
The cell to which your client machine belongs is called your local cell. All other cells in the AFS filespace are termed foreign cells.
The storage disks in a computer are divided into sections called partitions. AFS further divides partitions into units called volumes, each of which houses a subtree of related files and directories. The volume provides a convenient container for storing related files and directories. Your system administrators can move volumes from one file server machine to another without your noticing, because AFS automatically tracks a volume's location.
You access the contents of a volume by accessing its mount point in the AFS filespace. A mount point is a special file system element that looks and acts like a regular UNIX directory, but tells AFS the volume's name. When you change to a different directory (by using the cd command, for example) you sometimes cross a mount point and start accessing the contents of a different volume than before. You normally do not notice the crossing, however, because AFS automatically interprets mount points and retrieves the contents of the new directory from the appropriate volume. You do not need to track which volume, partition, or file server machine is housing a directory's contents. If you are interested, though, you can learn a volume's location; for instructions, see Locating Files and Directories.
If your system administrator has followed the conventional practice, your home directory corresponds to one volume, which keeps its contents together on one partition of a file server machine. User volumes are typically named user.username. For example, the volume for a user named smith in the cell abc.com is called user.smith and is mounted at the directory /afs/abc.com/usr/smith.
Because AFS volumes are stored on different file server machines, when a machine becomes unavailable only the volumes on that machine are inaccessible. Volumes stored on other machines are still accessible. However, if a volume's mount point resides in a volume that is stored on an unavailable machine, the former volume is also inaccessible. For that reason, volumes containing frequently used directories (for example, /afs and /afs/cellname) are often copied and distributed to many file server machines.
Each volume has a size limit, or quota, assigned by the system administrator. A volume's quota determines the maximum amount of disk space the volume can consume. If you attempt to exceed a volume's quota, you receive an error message. For instructions on checking volume quota, see Displaying Volume Quota.
Volumes have completely independent quotas. For example, say that the current working directory is /afs/abc.com/usr/smith, which is the mount point for the user.smith volume with 1000 free blocks. You try to copy a 500 block file from the current working directory to the /afs/abc.com/usr/pat directory, the mount point for the volume user.pat. However, you get an error message saying there is not enough space. You check the volume quota for user.pat, and find that the volume only has 50 free blocks.
You can access the AFS filespace only when working on an AFS client machine. The Cache Manager on that machine is your agent in accessing information stored in the AFS filespace. When you access a file, the Cache Manager on your client machine requests the file from the appropriate file server machine and stores (caches) a copy of it on your client machine's local disk. Application programs on your client machine use the local, cached copy of the file. This improves performance because it is much faster to use a local file than to send requests for file data across the network to the file server machine.
Because application programs use the cached copy of a file, any changes you make are not necessarily stored permanently to the central version stored on the file server machine until the file closes. At that point, the Cache Manager writes your changes back to the file server machine, where they replace the corresponding parts of the existing file. Some application programs close a file in this way each time you issue their save command (and then immediately reopen the file so that you can continue working). With other programs, issuing the save command writes the changes only to the local cached copy. If you use the latter type of text editor, you need to close the file periodically to make sure your changes are stored permanently.
If a file server machine becomes inaccessible, you can continue working with the local, cached copy of a file fetched from that machine, but you cannot save your changes permanently until the server machine is again accessible.
When the central version of a file changes on the file server machine, the AFS File Server process running on that machine advises all other Cache Managers with copies of that file that their version is no longer valid. AFS has a special mechanism for performing these notifications efficiently. When the File Server sends the Cache Manager a copy of a modifiable file, it also sends a callback. A callback functions as a promise from the File Server to contact the Cache Manager if the centrally stored copy of the file is changed while it is being used. If that happens, the File Server breaks the callback. If you run a program that requests data from the changed file, the Cache Manager notices the broken callback and gets an updated copy of the file from the File Server. Callbacks ensure that you are working with the most recent copy of a file.
Note: | The callback mechanism does not guarantee that you immediately see the changes someone else makes to a file you are using. Your Cache Manager does not notice the broken callback until your application program asks it for more data from the file. |
Like a standard UNIX file system, AFS preserves only the changes to a file that are saved last, regardless of who made the changes. When collaborating with someone on the same files, you must coordinate your work to avoid overwriting each other's changes. You can use AFS access control lists (ACLs) to limit the ability of other users to access or change your files, and so prevent them from accidentally overwriting your files. See Protecting Your Directories and Files.
AFS makes it easy for many users to access the same files, but also uses several mechanisms to ensure that only authorized users access the AFS filespace. The mechanisms include the following:
AFS uses two related mechanisms to ensure that only authorized users access the filespace: passwords and mutual authentication. Both mechanisms require that a user prove his or her identity.
When you first identify yourself to AFS, you must provide the password associated with your username, to prove that you are who you say you are. When you provide the correct password, you become authenticated and your Cache Manager receives a token. A token is a package of information that is scrambled by an AFS authentication program using your AFS password as a key. Your Cache Manager can unscramble the token because it knows your password and AFS's method of scrambling.
The token acts as proof to AFS server programs that you are authenticated as a valid AFS user. It serves as the basis for the second means through which AFS creates security, called mutual authentication. Under mutual authentication, both parties communicating across the network prove their identities to one another. AFS requires mutual authentication whenever a server and client (most often, a Cache Manager) communicate with each other.
The mutual authentication protocol that AFS uses is designed to make it very difficult for people to authenticate fraudulently. When your Cache Manager contacts a File Server on your behalf, it sends the token you obtained when you authenticated. The token is encrypted with a key that only an AFS File Server can know. If the File Server can decrypt your token, it can communicate with your Cache Manager. In turn, the Cache Manager accepts the File Server as genuine because the File Server can decrypt and use the information in the token.
AFS uses access control lists (ACLs) to determine who can access the information in the AFS filespace. Each AFS directory has an ACL to specify what actions different users can perform on that directory and its files. An ACL can contain up to about 20 entries for users, groups, or both; each entry lists a user or group and the permissions it possesses.
The owner of a directory and system administrators can always administer an ACL. Users automatically own their home directories and subdirectories. Other non-owner users can define a directory's ACL only if specifically granted that permission on the ACL. For more information on ACLs, see Protecting Your Directories and Files .
A group is composed of one or more users and client machines. If a user belongs to a group that appears on an ACL, the user gets all of the permissions granted to that group, just as if the user were listed directly on the ACL. Similarly, if a user is logged into a client machine that belongs to a group, the user has all of the permissions granted to that group. For instructions on defining and using groups, see Using Groups.
All users who can access your cell's filespace, authenticated or not, are automatically assigned to a group called system:anyuser. For a discussion of placing the system:anyuser group on ACLs, see Extending Access to Users from Foreign Cells.
Note: | You can use the UNIX mode bits to control access on specific files within an AFS directory; however, the effect of these mode bits is different under AFS than in the standard UNIX file system. See File and Directory Protection. |
AFS is designed to be similar to the UNIX file system. For instance, many of the basic UNIX file manipulation commands (cp for copy, rm for remove, and so on) are the same in AFS as they are as in UNIX. All of your application programs work as they did before. The following sections describe some of the differences between a standard UNIX file system and AFS.
AFS enables users to share remote files as easily as local files. To access a file on a remote machine in AFS, you simply specify the file's pathname. In contrast, to access a file in a remote machine's UNIX file system, you must log into the remote machine or create a mount point on the local machine that points to a directory in the remote machine's UNIX file system.
AFS users can see and share all the files under the /afs root directory, given the appropriate privileges. An AFS user who has the necessary privileges can access a file in any AFS cell, simply by specifying the file's pathname. File sharing in AFS is not restricted by geographical distances or operating system differences.
To become an authenticated AFS user, you need to provide a password to AFS.
Your system administrator can tell you whether your machine uses an AFS-modified login utility or not. Then see the login instructions in Logging in and Authenticating with AFS.
AFS authentication passwords are stored in special AFS database, rather than in the local password file (/etc/passwd or equivalent). If your machine uses an AFS-modified login utility, you can change your password with a single command. If your machine does not use an AFS-modified login utility, you must issue separate commands to change your AFS and local passwords. See Changing Your Password.
AFS does not rely on the mode bit protections of a standard UNIX system (though its protection system does interact with these mode bits). Instead, AFS uses an access control list (ACL) to control access to each directory and its contents. The following list summarizes the differences between the two methods:
The kinds of failures you experience when a standard UNIX file system goes down are different than when one or more individual AFS file server machines become unavailable. When a standard UNIX file system is inaccessible, the system simply locks up and you can lose changes to any files with which you were working.
When an AFS file server machine becomes inaccessible, you cannot access the files on that machine. If a copy of the file is available from another file server machine, however, you do not necessarily even notice the server outage. This is because AFS gives your cell's system administrators the ability to store copies of popular programs on multiple file servers. The Cache Manager chooses between the copies automatically; when one copy becomes unavailable, the Cache Manager simply chooses another.
If there are no other copies of a file that is stored on an inaccessible server machine, you can usually continue to use the copy stored in your client machine's local AFS cache. However, you cannot save changes to files stored on an inaccessible file server machine until it is accessible again.
The UNIX remote commands enable you to run programs on a remote machine without establishing a connection to it by using a program such as telnet. Many of the remote commands (such as ftp, rcp, and rsh) remain available in AFS, depending on how your administrators have configured them. If the remote machine has a Cache Manager, your token is used there also and you are authenticated while the remote command runs. If the remote machine does not run a Cache Manager, you receive the following message:
Warning: unable to authenticate.
In this case, you are logged into the remote machine's UNIX file system, but you are not authenticated to AFS. You can access the local files on the remote machine and the AFS directories that grant access to the system:anyuser group, but you cannot access protected AFS directories.
This section summarizes differences in the functionality of some commonly issued UNIX commands.
Some cells use the Networking File System (NFS) in addition to AFS. If you work on an NFS client machine, your system administrator can configure it to access the AFS filespace through a program called the NFS/AFS TranslatorTM. See Appendix A, Using the NFS/AFS Translator.
This chapter explains how to perform four basic AFS tasks: logging in and authenticating with AFS, ending an AFS session, accessing the AFS filespace, and changing your password.
To access the AFS filespace as an authenticated user, you must both log into an AFS client machine's local (UNIX) file system and authenticate with AFS. When you log in, you establish your local system identity. When you authenticate, you prove your identity to AFS and obtain a token, which your Cache Manager uses to prove your authenticated status to the AFS server processes it contacts on your behalf. Users who are not authenticated (who do not have a token) have limited access to AFS directories and files.
On machines that use an AFS-modified login utility, you log in and authenticate in one step. On machines that do not use an AFS-modified login utility, you log in and authenticate in separate steps. To determine which type of login utility your machine uses, you can check for AFS tokens after logging in, or ask your system administrator, who can also tell you about any differences between your login procedure and the two methods described here.
Provide your username at the login: prompt that appears when you establish a new connection to a machine. Then provide your password at the Password: prompt as shown in the following example. (Your password does not echo visibly on the screen.)
login: username Password: password
If you are not sure which type of login utility is running on your machine, it is best to issue the tokens command to check if you are authenticated; for instructions, see To Display Your Tokens. If you do not have tokens, issue the klog command as described in To Authenticate with AFS.
If your machine does not use an AFS-modified login utility, you must perform a two-step procedure:
% klog -setpag Password: your_AFS_password
Note: | If your machine uses a two-step login procedure, you can choose to use different passwords for logging in and authenticating. It is simplest to use the same one for both, though. Talk with your system administrator. |
To work most effectively in the AFS filespace, you must authenticate with AFS. When you do, your Cache Manager is given a token as proof of your authenticated status. It uses your token when requesting services from AFS servers, which accept the token as proof of your authenticated status. If you do not have a token, AFS servers consider you to be the anonymous user and your access to AFS filespace is limited: you have only the ACL permissions granted to the system:anyuser group.
You can obtain new tokens (reauthenticate) at any time, even after using an AFS-modified login utility, which logs you in and authenticates you in one step. Issue the klog command as described in To Authenticate with AFS.
To make your access to AFS as secure as possible, it is best to associate your tokens with a unique identification number called a PAG (for process authentication group). AFS-modified login utilities automatically create a PAG and associate the new token with it. To create a PAG when you use the two-step login procedure, include the klog command's -setpag flag. If you do not use this flag, your tokens are associated with your UNIX UID number instead. This type of association has two potential drawbacks:
A token is valid only in one cell (the cell whose AFS authentication service issued it). The AFS server processes in any other cell consider you to be the anonymous user unless you have an account in the cell and authenticate with its AFS authentication service.
To obtain tokens in a foreign cell, use the -cell argument to the klog command. You can have tokens for your home cell and one or more foreign cells at the same time.
You can have only one token per cell for each PAG you have obtained on a client machine. If you already have a token for a particular cell and issue the klog command, the new token overwrites the existing one. Getting a new token is useful if your current token is almost expired but you want to continue accessing AFS files. For a discussion of token expiration, see Token Lifetime.
To obtain a second token for the same cell, you must either login on a different machine or establish another separate connection to the machine where you already have a token (by using the telnet utility, for example). You get a new PAG for each separate machine or connection, and can use the associated tokens only while working on that machine or connection.
You can authenticate as another username if you know the associated password. (It is, of course, unethical to use someone else's tokens without permission.) If you use the klog command to authenticate as another AFS username, you retain your own local (UNIX) identity, but the AFS server processes recognize you as the other user. The new token replaces any token you already have for the relevant cell (for the reason described in The One-Token-Per-Cell Rule).
Tokens have a limited lifetime. To determine when your tokens expire, issue the tokens command as described in To Display Your Tokens. If you are ever unable to access AFS in a way that you normally can, issuing the tokens command tells you whether an expired token is a possible reason.
Your cell's administrators set the default lifetime of your token. The AFS authentication service never grants a token lifetime longer than the default, but you can request a token with a shorter lifetime. See the klog reference page in the IBM AFS Administration Reference to learn how to use its -lifetime argument for this purpose.
If your machine is configured to access a DCE cell's DFS filespace by means of the AFS/DFS Migration Toolkit, you can use the dlog command to authenticate with DCE. The dlog command has no effect on your ability to access AFS filespace.
If your system administrator has converted your AFS account to a DCE account and you are not sure of your DCE password, use the dpass command to display it. You must be authenticated as the AFS user whose AFS account was converted to a DCE account, and be able to provide the correct AFS password. Like the dlog command, the dpass command has no functionality with respect to AFS.
For more information on using the dlog and dpass commands, see your system administrator.
If your machine is not using an AFS-modified login utility, you must authenticate after login by issuing the klog command. You can also issue this command at any time to obtain a token with a later expiration date than your current token.
% klog [-setpag] [-cell <cell name>] Password: your_AFS_password
where
Your password does not echo visibly appear on the screen. When the command shell prompt returns, you are an authenticated AFS user. You can use the tokens command to verify that you are authenticated, as described in the following section.
Use the tokens command to display your tokens.
% tokens
The following output indicates that you have no tokens:
Tokens held by the Cache Manager: --End of list--
If you have one or more tokens, the output looks something like the following example, in which the tokens for AFS UID 1022 in the abc.com cell expire on August 3 at 2:35 p.m. The tokens for AFS UID 9554 in the stateu.edu cell expire on August 4 at 1:02 a.m.
Tokens held by the Cache Manager: User's (AFS ID 1022) tokens for afs@abc.com [Expires Aug 3 14:35] User's (AFS ID 9554) tokens for afs@stateu.edu [Expires Aug 4 1:02] --End of list--
Suppose that user terry cannot save a file. He uses the tokens command and finds that his tokens have expired. He reauthenticates in his local cell under his current identity by issuing the following command:
% klog Password: terry's_password
The he issues the tokens command to make sure he is authenticated.
% tokens Tokens held by the Cache Manager: User's (AFS ID 4562) tokens for afs@abc.com [Expires Jun 22 14:35] --End of list--
Now terry authenticates in his local cell as another user, pat. The new token replaces terry's existing token, because the Cache Manager can store only one token per cell per login session on a machine.
% klog pat Password: pat's_password % tokens Tokens held by the Cache Manager: User's (AFS ID 4278) tokens for afs@abc.com [Expires Jun 23 9:46] --End of list--
Now terry authenticates in the stateu.edu cell where his account is called ts09.
% klog ts09 -cell stateu.edu Password: ts09's_password % tokens Tokens held by the Cache Manager: User's (AFS ID 4562) tokens for afs@abc.com [Expires Jun 22 14:35] User's (AFS ID 8346) tokens for afs@stateu.edu [Expires Jun 23 1:02] --End of list--
Your system administrator can choose to limit the number of times that you fail to provide the correct password when authenticating with AFS (using either an AFS-modified login utility or the klog command). If you exceed the limit, the AFS authentication service refuses further authentication attempts for a period of time set by your system administrator. The purpose of this limit is to prevent unauthorized users from breaking into your account by trying a series of passwords.
To determine if your user account is subject to this limit, ask your system administrator or issue the kas examine command as described in To Display Your Failed Authentication Limit and Lockout Time.
The following message indicates that you have exceeded the limit on failed authentication attempts.
Unable to authenticate to AFS because ID is locked - see your system admin
Issue the kas examine command to determine if there is a limit on the number of unsuccessful authentication attempts for your user account and any associated lockout time. You can examine only your own account. The fourth line of the output reports the maximum number of times you can provide an incorrect password before being locked out of your account. The lock time field on the next line reports how long the AFS authentication service refuses authentication attempts after the limit is exceeded.
% kas examine your_username Password for your_username: your_AFS_password
The following example displays the output for the user pat, who is allowed nine failed authentication attempts. The lockout time is 25.5 minutes.
User data for pat key (15) cksum is 3414844392, last cpw: Thu Oct 21 16:05:44 1999 password will expire: Fri Nov 26 20:44:36 1999 9 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 Wed Aug 18 08:22:29 1999 by admin permit password reuse
Because logging in and authenticating with AFS are distinct operations, you must both logout and unauthenticate (issue the unlog command to discard your tokens) when exiting an AFS session. Simply logging out does not necessarily destroy your tokens.
You can use the unlog command any time you want to unauthenticate, not just when logging out. For instance, it is a good practice to unauthenticate before leaving your machine unattended, to prevent other users from using your tokens during your absence. When you return to your machine, issue the klog command to reauthenticate, as described in To Authenticate with AFS.
Do not issue the unlog command when you are running jobs that take a long time to complete, even if you are logging out. Such processes must have a token during the entire time they need authenticated access to AFS.
If you have tokens from multiple cells and want to discard only some of them, include the unlog command's -cell argument.
Issue the unlog command to discard your tokens:
% unlog -cell <cell name>+
Omit the -cell argument to discard all of your tokens, or use it to name each cell for which to discard tokens. It is best to provide the full name of each cell (such as stateu.edu or abc.com).
You can issue the tokens command to verify that your tokens were destroyed, as in the following example.
% tokens Tokens held by the Cache Manager: --End of list--
In the following example, a user has tokens in both the accounting and marketing cells at her company. She discards the token for the acctg.abc.com cell but keeps the token for the mktg.abc.com cell.
% tokens Tokens held by the Cache Manager: User's (AFS ID 35) tokens for afs@acctg.abc.com [Expires Nov 10 22:30] User's (AFS ID 674) tokens for afs@mktg.abc.com [Expires Nov 10 18:44] --End of list-- % unlog -cell acctg.abc.com % tokens Tokens held by the Cache Manager: User's (AFS ID 674) tokens for afs@mktg.abc.com [Expires Nov 10 18:44] --End of list--
After you have unauthenticated, log out by issuing the command appropriate for your machine type, which is possibly one of the following.
% logout
or
% exit
or
% <Ctrl-d>
While you are logged in and authenticated, you can access files in AFS just as you do in the UNIX file system. The only difference is that you can access potentially many more files. Just as in the UNIX file system, you can only access those files for which you have permission. AFS uses access control lists (ACLs) to control access, as described in Protecting Your Directories and Files.
AFS pathnames look very similar to UNIX file system names. The main difference is that every AFS pathname begins with the AFS root directory, which is called /afs by convention. Having /afs at the top of every AFS cell's filespace links together their filespaces into a global filespace.
Note for Windows users: Windows uses a backslash ( \ ) rather than a forward slash ( / ) to separate the elements in a pathname. Otherwise, your access to AFS filespace is much the same as for users working on UNIX machines.
The second element in AFS pathnames is generally a cell's name. For example, the ABC Corporation cell is called abc.com and the pathname of every file in its filespace begins with the string /afs/abc.com. Some cells also create a directory at the second level with a shortened name (such as abc for abc.com or stateu for stateu.edu), to reduce the amount of typing necessary. Your system administrator can tell you if your cell's filespace includes shortened names like this. The rest of the pathname depends on how the cell's administrators organized its filespace.
To access directories and files in AFS you must both specify the correct pathname and have the required permissions on the ACL that protects the directory and the files in it.
The user terry wants to look for a file belonging to another user, pat. He issues the ls command on the appropriate pathname.
% ls /afs/abc.com/usr/pat/public doc/ directions/ guide/ jokes/ library/
You can access files not only in your own cell, but in any AFS cell that you can reach via the network, regardless of geographical location. There are two additional requirements:
The alternative is for the foreign cell's administrator to create an account for you, essentially making you a local user in the cell. The directory's owner creates an ACL entry for you as for any other local user. To authenticate in the foreign cell, issue the klog command with the -cell argument.
For further discussion of directory and file protection, see Protecting Your Directories and Files.
In cells that use an AFS-modified login utility, the password is the same for both logging in and authenticating with AFS. In this case, you use a single command, kpasswd, to change the password.
If your machine does not use an AFS-modified login utility, there are separate passwords for logging into the local file system and authenticating with AFS. (The two passwords can be the same or different, at your discretion.) In this case, use the kpasswd command to change your AFS password and the UNIX passwd command to change your UNIX password.
Your system administrator can improve cell security by configuring several features that guide your choice of password. Keep them in mind when you issue the kpasswd command:
You can change your password prior to the expiration date, but your system administrator can choose to set a minimum time between password changes. The following message indicates that the minimum time has not yet passed.
kpasswd: password was not changed because you changed it too recently; see your system administrator
kpasswd: Password was not changed because it seems like a reused password
Issue the kas examine command to display your password expiration date and reuse policy. You can examine only your own account. The third line of the output reports your password's expiration date. The last line reports the password reuse policy that applies to you.
% kas examine your_username Password for your_username: your_AFS_password
The following example displays the output for the user pat.
User data for pat key (15) cksum is 3414844392, last cpw: Thu Oct 21 16:05:44 1999 password will expire: Fri Nov 26 20:44:36 1999 9 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 Wed Aug 18 08:22:29 1999 by admin don't permit password reuse
Issue the kpasswd command, which prompts you to provide your old and new passwords and to confirm the new password. The passwords do not echo visibly on the screen.
% kpasswd Old password: current_password New password (RETURN to abort): new_password Retype new password: new_password
Issue the UNIX passwd command, which prompts you to provide your old and new passwords and to confirm the new password. The passwords do not echo visibly on the screen. On many machines, the passwd resides in the /bin directory, and you possibly need to type the complete pathname.
% passwd Changing password for username. Old password: current_password New password: new_password Retype new passwd: new_password
This chapter explains how to display information that can help you use AFS more effectively. It includes the following sections.
Locating Files and Directories.
Checking the Status of Server Machines
Determining Access to Foreign Cells
By convention, the files in your home directory are stored together in a single volume. (For information about volumes, see Volumes and Mount Points.) To allocate your cell's available disk space as fairly as possible, your system administrators impose a size limit, or quota, on each volume. You cannot store more data in a volume than its quota allows. If a volume is close to its quota, you sometimes cannot save changes you have made to files stored in the volume.
The amount of space available on the partition that houses the volume also limits how large the volume can grow. If the disk partition is full, you can become unable to save changes to a file even though the volume is not close to its quota.
Check the quota on your home volume periodically to make sure you have adequate space. Also, if you encounter problems saving a file, check the quota of the volume in which the file is stored. Use the following commands to display volume quota.
Issue the fs quota command to display the percentage of the quota currently used for the volume that contains a specified directory or file.
% fs quota [<dir/file path>+]
where dir/file path specifies the pathname of a file or directory in each volume for which to display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains the current working directory.
The following example displays the percentage of quota used for the volumes that contain two user home directories in the ABC Corporation cell.
% cd /afs/abc.com/usr % fs quota terry pat 34% of quota used. 85% of quota used.
Issue the fs listquota command to display the following information:
The command's syntax is as follows.
% fs listquota [<dir/file path>+]
where dir/file path specifies the pathname of a file or directory in each volume for which to display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains the current working directory.
The following example displays quota information about the volume that houses the home directory of user terry.
% fs listquota ~terry Volume Name Quota Used % Used Partition user.terry 10000 3400 34% 86%
Issue the fs examine command to display the following information about a volume and the partition it resides on:
The command's syntax is as follows.
% fs examine [<dir/file path>+]
where dir/file path specifies the pathname of a file or directory in each volume for which to display quota information. If you do not provide a pathname, the output reports quota information for the volume that contains the current working directory.
The following example displays quota and other information about the volume that houses the current working directory.
% fs examine Volume status for vid = 536871122 named user.terry Current disk quota is 10000 Current blocks used are 5745 The partition has 1593 blocks available out of 99162
Normally, you do not need to know which file server machine stores the volume containing a file or directory. Given the pathname to a file, the Cache Manager on your client machine automatically accesses the appropriate server machine.
If you become unable to access a file, however, it can be useful to know which file server machine houses it. You can then check whether the File Server process or machine is functioning correctly, as described in Checking the Status of Server Machines. Or, if your system administrators schedule downtime for a machine, you can learn whether the outage is likely to prevent you from accessing certain files.
Issue the fs whereis command to display the file server machine on which a file or directory is stored.
% fs whereis [<dir/file path>+]
where dir/file path specifies the pathname of each file or directory for which you want location information. If you do not provide a pathname, the output reports the machine housing the volume that contains the current working directory.
If the output mentions more than one machine, there is a copy of the volume at each site (the volume is replicated). Your system administrators can choose to replicate volumes that contain information many people need to use, both for load balancing reasons and to make the information available even if there is an outage on one machine that houses the volume.
The following example displays the names of the server machines that house the home volumes for users terry and pat.
% cd /afs/abc.com/usr % fs whereis terry pat File /afs/abc.com/usr/terry is on host fs2.abc.com File /afs/abc.com/usr/pat is on host fs3.abc.com
Sometimes one or more server machines in your cell become inaccessible due to hardware problems, software problems, or routine maintenance. During the outage, you cannot access files stored on those machines or save any changes you have made to files that are stored on those machines. (Your Cache Manager possibly has copies of the files stored locally, which you can still work with.)
To check the status of server machines, use the fs checkservers command. If a server machine has more than one network interface address (is multihomed), the Cache Manager sends the status-checking message to all of the machine's interfaces. If at least one of the server's interfaces replies, the command's output reports the machine as accessible. If there is no reply from any of the interfaces, the output reports the machine as inaccessible but displays only one of the interfaces (usually the one with the best preference rank; see Displaying Server Preference Ranks).
To check the status of different groups of server machines, combine the fs checkservers command's options as indicated:
It can take several minutes for the command shell prompt to return, because the fs command interpreter waits a timeout period before concluding that an unresponsive machine is really inaccessible. To have the command shell prompt return immediately, add the ampersand (&), which runs the fs checkservers command in the background.
Issue the fs checkservers command to check the status of file server machines.
% fs checkservers [-cell <cell to check>] [-all] [&]
where
The following message indicates that all server machines replied to the Cache Manager's status-checking message:
All servers are running.
Otherwise, a message like the following lists the inaccessible machines:
These servers unavailable due to network or server problems: list of machines.
The following example checks the status of every file server machine the Cache Manager has contacted in any cell. Two machines are not responding.
% fs checkservers -all & These servers unavailable due to network or server problems: fs1.abc.com server7.stateu.edu.
The Cache Manager maintains a list of foreign cells that it knows how to reach. A cell must appear in the list for you to access its AFS filespace. (In addition, the ACL on each directory in the pathname to the file must grant you the necessary permissions, and your system administrator must mount the cell in the local AFS filespace--by convention, just under the /afs directory.)
Issue the fs listcells command to display the cells you can access from this client machine. It can take several minutes for the command shell prompt to return. The Cache Manager stores the machines as IP addresses, but has the addresses translated to names before displaying them. To have the command shell prompt return immediately, use the ampersand (&) to run the fs listcells command in the background as in the following example.
% fs listcells & Cell abc.com on hosts db1.abc.com db2.abc.com db3.abc.com Cell test.abc.com on hosts test4.abc.com. Cell stateu.edu on hosts sv5.stateu.edu. sv2.stateu.edu. sv11.stateu.edu. Cell def.com on hosts serverA.def.com
The Cache Manager stores a list of preference ranks for file server machines. When it needs to access a file or directory, the Cache Manager compares the ranks of the file server machines that house the relevant volume. It first tries to access the volume on the machine with the best rank. (If a file server machine is multihomed--has more than one network interface--the Cache Manager actually assigns a separate rank to each interface.)
The Cache Manager assigns a default rank to a file server machine interface by comparing its own IP address to the interface's IP address. It assigns a better rank to interfaces that are on its own subnetwork or network than to interfaces on other networks. Therefore, the ranks bias the Cache Manager to fetch files from file server machines that are close in terms of network distance, which tends to reduce network traffic and help the Cache Manager deliver data to applications more quickly.
The Cache Manager stores each rank as a pairing of a file server machine interface's IP address and an integer rank from the range 0 to 65,534. A lower number is a better rank. To display the server preference ranks on the local client machine, use the fs getserverprefs command.
The Cache Manager stores a separate but similar set of ranks for Volume Location (VL) Servers, which tell the Cache Manager the location of volumes that house files and directories. To display those ranks, add the -vlservers flag to the fs getserverprefs command.
If the default ranks do not seem to result in the best performance, your system administrator can change them. Ask your system administrator about the ranks if appropriate.
Issue the fs getserverprefs command to display the file server machine preference ranks used by the Cache Manager on the local machine. To display VL Server ranks, add the -vlservers flag. By default, the Cache Manager has the IP address of each interface translated into a hostname before displaying it. To bypass the translation and display IP addresses, include the -numeric flag. This can significantly speed up the command's output.
% fs getserverprefs [-numeric] [-vlservers]
The following example displays the file server machine preference ranks for a client machine in the abc.com cell. The ranks of the file server machines in that cell are lower than the ranks of the file server machines from the foreign cell, def.com. Because the -numeric flag is not used, the output displays hostnames. The appearance of an IP address for two machines indicates that translating them was not possible.
% fs getserverprefs fs2.abc.com 20007 fs3.abc.com 30002 fs1.abc.com 20011 fs4.abc.com 30010 server1.def.com 40002 192.12.105.34 40000 server6.def.com 40012 192.12.105.37 40005
This chapter explains how to protect AFS files and directories by defining permissions on an access control list.
AFS augments and refines the standard UNIX scheme for controlling access to files and directories. Instead of using mode bits to define access permissions for individual files, as UNIX does, AFS stores an access control list (ACL) with each directory. It defines which users and groups can access the directory and the files it contains, and in what manner. An ACL can store up to about 20 entries, each of which pairs a user or group and a set of permissions. AFS defines seven permissions rather than the three that UNIX uses.
Another refinement to the standard UNIX protection scheme is that users can define their own protection groups and then place the groups on ACLs as though they were individual users. A group can include both users and machines. Each user who belongs to a group inherits all of the permissions granted to the group on the ACL. Similarly, all users who are logged into a machine that belongs to a group inherits all of the permissions granted to the group. You can create groups to place on ACLs and also use groups that other users have created. To learn more about group creation, see Using Groups.
In addition, AFS defines two system groups called system:anyuser and system:authuser. By placing them on ACLs, you can grant access to large numbers of users at once. See Using the System Groups on ACLs.
Although AFS uses ACLs to protect files and directories, it also uses the UNIX mode bits to a limited extent. See How AFS Uses the UNIX Mode Bits.
As noted, AFS associates an ACL with each directory, and it applies to all of the files stored in the directory. Files do not have separate ACLs. Defining access at the directory level has several consequences:
As a general rule, it makes sense to grant fairly liberal access to your home directory. If you need to protect certain files more closely, place them in subdirectories that have more restrictive ACLs.
There are seven standard AFS ACL permissions. Functionally, they fall into two groups: one that applies to the directory itself and one that applies to the files.
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.
This permission enables a user to issue the following commands:
This permission does not enable a user to read the contents of a file in the directory or to issue the ls -l or fs listacl commands with a filename as the 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 three permissions in this group are meaningful with respect to files in a directory, rather than the directory itself or its subdirectories.
AFS provides eight additional permissions that do not have a defined meaning. They are denoted by the uppercase letters A, B, C, D, E, F, G, and H.
Your system administrator can choose to 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. Use the fs listacl and fs setacl commands to display and set the auxiliary permissions on ACLs just like the standard seven.
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:
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 Changing an ACL. When you use the fs listacl command to display an ACL (as described in Displaying an ACL), 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:
Negative rights
When determining what type of access to grant to a user, AFS first examines all of the entries in the normal permissions section of the ACL. It then subtracts any permissions associated with the user (or with groups to which the user belongs) on the negative permissions section of the ACL. Therefore, negative permissions always cancel out normal permissions.
Negative permissions can be confusing, because they reverse the usual meaning of the fs setacl command. In particular, combining the none shorthand and the -negative flag is a double negative: by removing an entry from the negative permissions section of the ACL, you enable a user once again to obtain permissions via entries in the normal permissions section. Combining the all shorthand with the -negative flag explicitly denies all permissions.
It is useless to create an entry in the negative permissions section if an entry in the normal permissions 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, AFS recognizes them as the anonymous user, who belongs to the system:anyuser group but does not match the entries on the negative permissions section of the ACL.
If your machine is configured to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, then you can use the AFS fs listacl and fs setacl commands to display and set the ACLs on DFS directories and files that you own. However, DFS uses a slightly different set of permissions and a different syntax for ACL entries. See the DFS documentation or ask your system administrator.
AFS defines two system groups that grant access to a large number of users at once when placed on an ACL. However, you cannot control the membership of these groups, so consider carefully what kind of permissions you wish to give them. (You do control the membership of the groups you own; see Using Groups.)
The third system group, system:administrators, includes a small group of administrators who have extensive permissions in the cell. You do not generally need to put this group on your ACLs, because its members always have the a (administer) permission on every ACL, even if the group does not appear on it.
A user must have the l permission on a directory to access its subdirectories in any way. Even if users have extensive permissions on a subdirectory, they cannot access it if the parent directory's ACL does not grant the l permission.
You can grant the l permission in one of three ways: grant it to a system group (system:anyuser or system:authuser), grant it to individual users, or grant it to one or more groups of users defined by you or other users (see Using Groups). Granting the l permission to the system:anyuser group is the easiest option and is generally secure because the permission only enables users to list the contents of the directory, not to read the files in it. If you want to enable only locally authenticated users to list a directory's contents, substitute the system:authuser group for the system:anyuser group. Your system administrator has possibly already created an entry on your home directory's ACL that grants the r and l permissions to the system:anyuser group.
It is sometimes necessary to grant more extensive permissions to the system:anyuser group so that processes that provide printing and mail delivery service can work correctly. For example, printing processes sometimes need the r permission in addition to the l permission. A mail delivery process possibly needs the i permission to place new messages in your mail directory. Your system administrator has probably already created the necessary ACL entries. If you notice an ACL entry for which the purpose is unclear, check with your system administrator before removing it.
The only way to grant access to users from foreign cells who do not have an account in your cell is to put the system:anyuser group on an ACL. Remember, however, that such an entry extends access to everyone who can reach your cell, not just the AFS users from foreign cells that you have in mind.
To display the ACL associated with a file or directory, issue the fs listacl command.
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 or Initial Object ACL instead of the regular one, include the fs listacl command's -id or -if flag. For more information, ask your system administrator. The fs command interpreter ignores the -id and -if flags if you include them when displaying an AFS ACL.
% fs listacl [<dir/file path>+]
where
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.
If the following error message appears instead of an ACL, 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'
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 rights: system:authuser rl pat rlw terry rlidwka Negative rights: 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 rlw permissions to pat, and the rl permissions to the members of the system:authuser group.
The list of negative permissions denies the rl 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; they cancel out the rl permissions extended to the system:authuser group, which is the only entry on the normal permissions section of the ACL that possibly applies to them.
The following example illustrates how you can specify pathnames in different ways, and the appearance of the output for multiple directories. It displays the ACL for three directories: the current working directory (which is a subdirectory of user terry's home directory), the home directory for user pat, and another subdirectory of terry's home directory called plans.
% fs listacl . /afs/abc.com/usr/pat ../plans Access list for . is Normal rights: system:anyuser rl pat:dept rliw Access list for /afs/abc.com/usr/pat is Normal rights: system:anyuser rl pat rlidwka terry rliw Access list for ../plans is Normal rights: terry rlidwka pat rlidw
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 as instructed in To Add, Remove, or Edit Negative ACL Permissions.
You can change any ACL on which you already have the a permission. You always have the a permission on the ACL of every directory that you own, even if you accidentally remove that permission from the ACL. (The ls -ld command reports a directory's owner.) Your system administrator normally designates you as the owner of your home directory and its subdirectories, and you possibly own other directories also.
If an ACL entry already exists for the user or group you specify, then the new permissions completely replace the existing permissions rather than being added to them. In other words, when issuing the fs setacl command, you must include all permissions that you want to grant to a user or group.
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 or Initial Object ACL instead of the regular one, include the fs setacl command's -id or -if flag. For more information, ask your system administrator. The fs command interpreter ignores the -id and -if flags if you include them when setting an AFS ACL.
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 for a user or group, the permissions you specify completely replace those in the existing entry.
% fs setacl -dir <directory>+ -acl <access list entries>+
where
fs: 'filename': Not a directory
If you specify only one directory (or file) name, you can omit the -dir and -acl switches. For more on omitting switches, see Appendix B, AFS Command Syntax and Online Help.
To define the permissions, provide either:
On a single command line, you can combine user and group entries. Also, you can both combine individual letters and use the shorthand notations, but not within a single pair.
Either of the following example commands grants user pat the r and l permissions on the ACL of the notes subdirectory of the current working 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 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 to the members of the terry:colleagues group and the other grants the r and l permissions to the system:authuser group.
% fs sa -dir . -acl system:anyuser none terry:colleagues write \ system:authuser rl
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
User terry has granted all access permissions except a to the group terry:team on her plans subdirectory.
% cd /afs/abc.com/usr/terry % fs listacl plans Access control list for plans is Normal rights: system:anyuser rl terry:team rlidwk terry rlidwka
However, terry notices that one of the members of the group, user pat, has been making inappropriate changes to files. To prevent this without removing pat from the group or changing the permissions for the terry:team group, terry creates an entry on the negative permissions section of the ACL that denies the w and d permissions to pat:
% fs setacl plans pat wd -negative % fs listacl plans Access control list for plans is Normal rights: system:anyuser rl terry:team rlidwk terry: rlidwka Negative rights: pat wd
In the previous example, user terry put pat on the negative permissions section of ACL for the plans subdirectory. But the result has been inconvenient and pat has promised not to change files any more. To enable pat to exercise all permissions granted to the members of the terry:team group, terry removes the entry for pat from the negative permissions section of the ACL.
% fs setacl plans pat none -negative % fs listacl plans Access control list for plans is Normal rights: system:anyuser rl terry:team rlidwk terry rlidwka
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 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 for yourself. As the owner of the directory, you always have the a (administer) permission required to replace a deleted entry, but the effects the effects of a missing ACL entry can be confusing enough to make it difficult to realize that the problem is a missing entry. In particular, the lack of the l (lookup) permission prevents you from using any shorthand notation in pathnames (such as a period for the current working directory or two periods for the parent directory).
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
The following example clears the ACL on the current working directory and creates entries that grant all permissions to user terry and all permissions except a to user pat.
% fs setacl . terry all pat write -clear % fs listacl . Access control list for . is Normal rights: terry rlidwka pat rlidwk
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:
To copy an ACL, you must have the l permission on the source ACL and the a permission on each destination ACL. If you identify the source directory by naming a file in it, you must also have the r permission on the source ACL. To display the permissions you have on the two directories, use the fs listacl command as described in Displaying an ACL.
Note for AFS/DFS Migration Toolkit users: If the machine on which you issue the fs copyacl command is configured for access to a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can use the 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; for details, ask your system administrator. 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.
Issue the fs copyacl command to copy a source ACL to the ACL on one or more destination directories.
% fs copyacl -fromdir <source directory> -todir <destination directory>+ \ [-clear]
where
In this example, user terry copies the ACL from her home directory (the current working directory) to its plans subdirectory. She begins by displaying both ACLs.
% fs listacl . plans Access list for . is Normal rights: terry rlidwka pat rlidwk jones rl Access list for plans is Normal rights: terry rlidwka pat rl smith rl % fs copyacl -from . -to plans % fs listacl . plans Access list for . is Normal rights: terry rlidwka pat rlidwk jones rl Access list for plans is Normal rights: terry rlidwka pat rlidwk jones rl smith rl
Although AFS protects data primarily with ACLs rather than mode bits, it does not ignore the mode bits entirely. An explanation of how mode bits work in the UNIX file system is outside the scope of this document, and the following discussion assumes you understand them; if necessary, see your UNIX documentation. Also, the following discussion does not cover the setuid, setgid or sticky bits. If you need to understand how those bits work on AFS files, see the IBM AFS Administration Guide or ask your system administrator.
AFS uses the UNIX mode bits in the following way:
When you issue the UNIX 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 permission on the ACL of the file's directory. To change a directory's mode bits, you must have the d, i, and l permissions on its ACL.
Suppose terry is chairing a committee that is writing a proposal. As each section is approved, she turns off write access to that file to prevent further changes. For example, the following chmod command turns off the w mode bits on the file proposal.chap2. This makes it impossible for anyone to change the file, no matter what permissions are granted on the directory ACL.
% chmod -w proposal.chap2 % ls -l -rw-r--r-- 1 terry 573 Nov 10 09:57 conclusion -r--r--r-- 1 terry 573 Nov 15 10:34 intro -r--r--r-- 1 terry 573 Dec 1 15:07 proposal.chap2 -rw-r--r-- 1 terry 573 Nov 10 09:57 proposal.chap3 -rw-r--r-- 1 terry 573 Nov 10 09:57 proposal.chap4
This chapter explains how to create groups and discusses different ways to use them.
An AFS group is a list of specific users that you can place on access control lists (ACLs). Groups make it much easier to maintain ACLs. Instead of creating an ACL entry for every user individually, you create one entry for a group to which the users belong. Similarly, you can grant a user access to many directories at once by adding the user to a group that appears on the relevant ACLs.
AFS client machines can also belong to a group. Anyone logged into the machine inherits the permissions granted to the group on an ACL, even if they are not authenticated with AFS. In general, groups of machines are useful only to system administrators, for specialized purposes like complying with licensing agreements your cell has with software vendors. Talk with your system administrator before putting a client machine in a group or using a machine group on an ACL.
To learn about AFS file protection and how to add groups to ACLs, see Protecting Your Directories and Files.
There are three typical ways to use groups, each suited to a particular purpose: private use, shared use, and group use. The following are only suggestions. You are free to use groups in any way you choose.
The existence of the group and the identity of its members is not necessarily secret. Other users can see the group's name on an ACL when they use the fs listacl command, and can use the pts membership command to display + the groups to which they themselves belong. You can, however, limit who can display the members of the group, as described in Protecting Group-Related Information.
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. |
The main advantage of designating a group as an owner is that several people share responsibility for administering the group. A single person does not have to perform all administrative tasks, and if the group's original owner leaves the cell, there are still other people who can administer it.
However, everyone in the owner group can make changes that affect others negatively: 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.
The groups you create must have names with two parts, in the following format:
owner_name:group_name
The owner_name prefix indicates which user or group owns the group (naming rules appear in To Create a Group). The group_name part indicates the group's purpose or its members' common interest. Group names must always be typed in full, so a short group_name is most practical. However, names like terry:1 and terry:2 that do not indicate the group's purpose are less useful than names like terry:project.
Groups that do not have the owner_name prefix possibly appear on some ACLs; they are created by system administrators only. All of the groups you create must have an owner_name prefix.
By default, you can create 20 groups, but your system administrators can change your group-creation quota if appropriate. When you create a group, your group quota decrements by one. When a group that you created is deleted, your quota increments by one, even if you are no longer the owner. You cannot increase your quota by transferring ownership of a group to someone else, because you are always recorded as the creator.
If you exhaust your group-creation quota and need to create more groups, ask your system administrator. For instructions for displaying your group-creation quota, see To Display A Group Entry.
You can use the following commands to display information about groups and the users who belong to them:
Note: | The system:anyuser and system:authuser system groups do not appear in a user's list of group memberships, and the pts membership command does not display their members. For more information on the system groups, see Using the System Groups on ACLs. |
Issue the pts membership command to display the members of a group, or the groups to which a user belongs.
% pts membership <user or group name or id>+
where user or group name or id specifies the name or AFS UID of each user for which to display group membership, or the name or AFS GID of each group for which to display the members. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.
The following example displays the members of the group terry:team.
% pts membership terry:team Members of terry:team (id: -286) are: terry smith pat johnson
The following example displays the groups to which users terry and pat belong.
% pts membership terry pat Groups terry (id: 1022) is a member of: smith:friends pat:accounting terry:team Groups pat (id: 1845) is a member of: pat:accounting sam:managers terry:team
Issue the pts listowned command to display the groups that a user or group owns.
% pts listowned <user or group name or id>+
where user or group name or id specifies the name or AFS UID of each user, or the name or AFS GID of each group, for which to display group ownership. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.
The following example displays the groups that the group terry:team owns.
% pts listowned -286 Groups owned by terry:team (id: -286) are: terry:project terry:planners
The following example displays the groups that user pat owns.
% pts listowned pat Groups owned by pat (id: 1845) are: pat:accounting pat:plans
Issue the pts examine command to display general information about a user or group, including its name, AFS ID, creator, and owner.
% pts examine <user or group name or id>+
where user or group name or id specifies the name or AFS UID of each user, or the name or AFS GID of each group, for which to display group-related information. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.
The output includes information in the following fields:
The following example displays information about the group pat:accounting, which includes members of the department that pat manages. Notice that the group is self-owned, which means that all of its members can administer it.
% pts examine pat:accounting Name: pat:accounting, id: -673, owner: pat:accounting, creator: pat, membership: 15, flags: S-M--, group quota: 0
The following example displays group-related information about user pat. The two most interesting fields are membership, which shows that pat belongs to 12 groups, and group quota, which shows that pat can create another 17 groups.
% pts examine pat Name: pat, id: 1045, owner: system:administrators, creator: admin, membership: 12, flags: S-M--, group quota: 17
Use the pts creategroup command to create a group and the pts adduser command to add members to it. Users and machines can belong to groups, but other groups cannot.
When you create a group, you normally become its owner automatically. This means you alone can administer it: add and remove members, change the group's name, transfer ownership of the group, or delete the group entirely. If you wish, you can designate another owner when you create the group, by including the -owner argument to the pts creategroup command. If you assign ownership to another group, the owning group must already exist and have at least one member. You can also change a group's ownership after creating it by using the pts chown command as described in Changing a Group's Owner or Name.
Issue the pts creategroup command to create a group. Your group-creation quota decrements by one for each group.
% pts creategroup -name <group name>+ [-owner <owner of the group>]
where
owner_name:group_name
The owner_name prefix must 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 or group as the owner, as long as you provide the required value in the owner_name field:
The name can include up to 63 characters including the colon. Use numbers and lowercase letters, but no spaces or punctuation characters other than the colon.
Do not name a machine as the owner. Because no one can authenticate as a machine, there is no way to administer a group owned by a machine.
In the following example user terry creates a group to include all the other users in his work team, and then examines the new group entry.
% pts creategroup terry:team group terry:team has id -286 % pts examine terry:team Name: terry:team, id: -286, owner: terry, creator: terry, membership: 0, flags: S----, group quota: 0.
Issue the pts adduser command to add one or more users to one or more groups. You can always add members to a group you own (either directly or because you belong to the owning group). If you belong to a group, you can add members if its fourth privacy flag is the lowercase letter a; see Protecting Group-Related Information.
% pts adduser -user <user name>+ -group <group name>+
You must add yourself to groups that you own, if that is appropriate. You do not belong automatically just because you own the group.
Note: | If you already have a token when you are added to a group, you must issue the klog command to reauthenticate before you can exercise the permissions granted to the group on ACLs. |
where
In this example, user terry adds himself, pat, indira, and smith to the group he just created, terry:team, and then verifies the new list of members.
% pts adduser -user terry pat indira smith -group terry:team % pts members terry:team Members of terry:team (id: -286) are: terry pat indira smith
You can use the following commands to remove groups and their members:
When a group that you created is deleted, your group-creation quota increments by one, even if you no longer own the group.
When a group or user is deleted, its AFS ID appears on ACLs in place of its AFS name. You can use the fs cleanacl command to remove these obsolete entries from ACLs on which you have the a (administer) permission.
Issue the pts removeuser command to remove one or more members from one or more groups. You can always remove members from a group that you own (either directly or because you belong to the owning group). If you belong to a group, you can remove members if its fifth privacy flag is the lowercase letter r; see Protecting Group-Related Information. (To display a group's owner, use the pts examine command as described in To Display A Group Entry.)
% pts removeuser -user <user name>+ -group <group name>+
where
The following example removes user pat from both the terry:team and terry:friends groups.
% pts removeuser pat -group terry:team terry:friends
Issue the pts delete command to delete a group. You can always delete a group that you own (either directly or because you belong to the owning group). To display a group's owner, use the pts examine command as described in To Display A Group Entry.
% pts delete <user or group name or id>+
where user or group name or id specifies the name or AFS UID of each user, or the name or AFS GID of each group, to delete. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.
In the following example, the group terry:team is deleted.
% pts delete terry:team
Issue the fs cleanacl command to remove obsolete entries from ACLs after the corresponding user or group has been deleted.
% fs cleanacl [<dir/file path>+]
where dir/file path name each directory for which to clean the ACL. If you omit this argument, the current working directory's ACL is cleaned.
After the group terry:team is deleted, its AFS GID (-286) appears on ACLs instead of its name. In this example, user terry cleans it from the ACL on the plans directory in his home directory.
% fs listacl plans Access list for plans is Normal rights: terry rlidwka -268 rlidwk sam rliw % fs cleanacl plans % fs listacl plans Access list for plans is Normal rights: terry rlidwka sam rliw
To change a group's owner, use the pts chown command. To change its name, use the pts rename command.
You can change the owner or name of a group that you own (either directly or because you belong to the owning group). You can assign group ownership to another user, another group, or the group itself. If you are not already a member of the group and need to be, use the pts adduser command before transferring ownership, following the instructions in To Add Members to a Group.
The pts chown command automatically changes a group's owner_name prefix to indicate the new owner. If the new owner is a group, only its owner_name prefix is used, not its entire name. However, the change in owner_name prefix command does not propagate to any groups owned by the group whose owner is changing. If you want their owner_name prefixes to indicate the correct owner, you must use the pts rename command.
Otherwise, you normally use the pts rename command to change only the group_name part of a group name (the part that follows the colon). You can change the owner_name prefix only to reflect the actual owner.
Issue the pts chown command to change a group's name.
% pts chown <group name> <new owner>
where
In the following example, user pat transfers ownership of the group pat:staff to user terry. Its name changes automatically to terry:staff, as confirmed by the pts examine command.
% pts chown pat:staff terry % pts examine terry:staff Name: terry:staff, id: -534, owner: terry, creator: pat, membership: 15, flags: SOm--, group quota: 0.
In the following example, user terry makes the terry:team group a self-owned group. Its name does not change because its owner_name prefix is already terry.
% pts chown terry:team terry:team % pts examine terry:team Name: terry:team, id: -286, owner: terry:team, creator: terry, membership: 6, flags: SOm--, group quota: 0.
In this example, user sam transfers ownership of the group sam:project to the group smith:cpa. Its name changes automatically to smith:project, because smith is the owner_name prefix of the group that now owns it. The pts examine command displays the group's status before and after the change.
% pts examine sam:project Name: sam:project, id: -522, owner: sam, creator: sam, membership: 33, flags: SOm--, group quota: 0. % pts chown sam:project smith:cpa % pts examine smith:project Name: smith:project, id: -522, owner: smith:cpa, creator: sam, membership: 33, flags: SOm--, group quota: 0.
Issue the pts rename command to change a group's name.
% pts rename <old name> <new name>
where
The following example changes the name of the smith:project group to smith:fiscal-closing. The group's owner_name prefix remains smith because its owner is not changing.
% pts examine smith:project Name: smith:project, id: -522, owner: smith:cpa, creator: sam, membership: 33, flags: SOm--, group quota: 0. % pts rename smith:project smith:fiscal-closing % pts examine smith:fiscal-closing Name: smith:fiscal-closing, id: -522, owner: smith:cpa, creator: sam, membership: 33, flags: SOm--, group quota: 0.
In a previous example, user pat transferred ownership of the group pat:staff to user terry. Its name changed automatically to terry:staff. However, a group that terry:staff owns is still called pat:plans, because the change to a group's owner_name that results from the pts chown command does not propagate to any groups it owns. In this example, a member of terry:staff uses the pts rename command to change the name to terry:plans to reflect its actual ownership.
% pts examine pat:plans Name: pat:plans, id: -535, owner: terry:staff, creator: pat, membership: 8, flags: SOm--, group quota: 0. % pts rename pat:plans terry:plans % pts examine terry:plans Name: terry:plans, id: -535, owner: terry:staff, creator: pat, membership: 8, flags: SOm--, group quota: 0.
A group's privacy flags control who can administer it in various ways. The privacy flags appear in the flags field of the output from the pts examine command command; see To Display A Group Entry. To set the privacy flags for a group you own, use the pts setfields command as instructed in To Set a Group's Privacy Flags.
The five privacy flags always appear, and always must be set, in the following order:
Each flag can take three possible types of values to enable a different set of users to issue the corresponding command:
For example, the flags SOmar on a group entry indicate that anyone can examine the group's entry and list the groups that it owns, and that only the group's members can list, add, or remove its members.
The default privacy flags for groups are S-M--, meaning that anyone can display the entry and list the members of the group, but only the group's owner and members of the system:administrators group can perform other functions.
Issue the pts setfields command to set the privacy flags on one or more groups.
% pts setfields -nameorid <user or group name or id>+ -access <set privacy flags>
where
The following example sets the privacy flags on the terry:team group to set the indicated pattern of administrative privilege.
% pts setfields terry:team -access SOm--
This chapter explains how to investigate and solve some problems you can sometimes encounter when working with AFS files. To use the instructions, find the heading that describes your problem or matches the error message you received.
% tokens
% klog
% fs checkservers &
All servers are running.
These servers unavailable due to network or server problem: list of machines.
Issue the fs whereis command to check if the file you are attempting to access or save is stored on one of the inaccessible file server machines. For complete instructions, see Locating Files and Directories.
% fs whereis <dir/file path>
If your file is stored on an inaccessible machine, then you cannot access the file or save it back to the File Server until the machine is again accessible. If your file is on a machine that is not listed as inaccessible, proceed to Step 3.
% fs listacl <dir/file path>
You need the indicated permissions:
If you do not have the necessary permissions but own the directory, you always have the a (administer) permission even if you do not appear on the ACL. Issue the fs setacl command to grant yourself the necessary permissions. For complete instructions, see Changing an ACL.
% fs setacl -dir <directory>+ -acl <access list entries>+
If you do not have the necessary permissions and do not own the directory, ask the owner or a system administrator to grant them to you. If they add you to a group that has the required permissions, you must issue the klog command to reauthenticate before you can exercise them.
If you still cannot access the file even though you have the necessary permissions, contact your system administrator for help in investigating further possible causes of your problem. If you still cannot copy or save the file even though you have the necessary permissions, proceed to Step 4.
% fs listquota <dir/file path>
The command produces output as in the following example:
% fs listquota /afs/abc.com/usr/terry Volume Name Quota Used % Used Partition user.terry 10000 3400 34% 86%
If the value in the % Used field is not close to 100% (is, say, 90% or less), then it is unlikely that you are exceeding the volume's quota, unless the file is very large or the volume's quota is small. Contact your system administrator for help in investigating further possible causes of your problem.
% fs examine <dir/file path>
If there is enough free space on the partition but you still cannot save the file, ask your system administrator for help in investigating further possible causes of your problem.
% fs setacl -dir <directory> -acl <your_username> all
For directory, provide the complete pathname to the directory (for example, /afs/abc.com/usr/your_username). This is necessary because AFS cannot interpret pathname abbreviations if you do not have the l (lookup) permission.
% fs listacl <dir/file path>
Access list for <dir/file path> is Normal rights list of entries
fs: You don't have the required access rights on 'dir/file path'
Ask the directory's owner or your system administrator to grant you the permissions you need. If they add you to a group that has the required permissions, you must issue the klog command to reauthenticate before you can exercise them.
Issue the fs checkservers command to check the status of file server machines. For complete instructions, see Checking the Status of Server Machines.
% fs checkservers &
All servers are running.
These servers unavailable due to network or server problem: list_of_machines.
Issue the fs checkservers command as described in Error Message: afs: Lost contact with fileserver.
You do not have the ACL permissions you need to perform the operation you are attempting. If you own the directory and have accidentally removed yourself from the ACL, see Problem: Accidentally Removed Your Entry from an ACL. Otherwise, ask the directory's owner or your system administrator to grant you the appropriate permissions.
Follow the instructions in Problem: Cannot Access, Copy, or Save File.
Some cells use the Network File System (NFS) in addition to AFS. If you work on an NFS client machine, your system administrator can configure it to access the AFS filespace through a program called the NFS/AFS TranslatorTM. If you have an AFS account, you can access AFS as an authenticated user while working on your NFS client machine. Otherwise, you access AFS as the anonymous user.
Note: | Acceptable NFS/AFS Translator performance requires that NFS is functioning correctly. |
For you to use the NFS/AFS Translator, your system administrator must configure the following types of machines as indicated:
Your access to AFS is much more extensive if you have an AFS user account. If you do not, the AFS servers recognize you as the anonymous user and only grant you the access available to members of the system:anyuser group.
If your NFS client machine uses an operating system that AFS supports, your system administrator can configure it to enable you to issue many AFS commands on the machine. Ask him or her about the configuration and which commands you can issue.
If you do not have an AFS account or choose not to access AFS as an authenticated user, then all you do to access AFS is provide the pathname of the relevant file. Its ACL must grant the necessary permissions to the system:anyuser group.
If you have an AFS account and want to access AFS as an authenticated user, the best method depends on whether your NFS machine is a supported type. If it is, use the instructions in To Authenticate on a Supported Operating System. If it is not a supported type, use the instructions in To Authenticate on an Unsupported Operating System.
% klog -setpag
% tokensIf you do not have tokens, issue the klog command, which is described fully in To Authenticate with AFS.
% klog -setpag
If your NFS client machine is a system type for which AFS defines a system name, it can make sense to add the -sysname argument. This argument helps the Cache Manager access binaries specific to your NFS client machine, if your system administrator has used the @sys variable in pathnames. Ask your system administrator if this argument is useful for you.
% knfs <host name> [<user ID (decimal)>] \ [-sysname <host's '@sys' value>]
where
% knfs <host name> [<user ID (decimal)>] -unlog
Acceptable performance by the NFS/AFS translator depends for the most part on NFS. Sometimes, problems that appear to be AFS file server outages, broken connections, or inaccessible files are actually caused by NFS outages.
This section describes some common problems and their possible causes. If other problems arise, contact your system administrator, who can ask the AFS Product Support group for assistance if necessary.
Note: | To avoid degrading AFS performance, the Cache Manager on the translator machine does not immediately send changes made on NFS client machines to the File Server. Instead, it checks every 60 seconds for such changes and sends them then. It can take longer for changes made on an NFS client machine to be saved than for changes made on an AFS client machine. The save operation must complete before the changes are visible on NFS client machines that are using a different translator machine or on AFS client machines. |
If your system administrator has used the recommended options when creating an NFS mount to an NFS/AFS translator machine, then the mount is both hard and interruptible:
If you have authenticated to AFS and your translator machine reboots, you must issue the klog command (and knfs command, if appropriate) to reauthenticate. If you used the knfs command's -sysname argument to define your NFS client machine's system name, use it again.
This section explains possible meanings for NFS error messages you receive while accessing AFS filespace.
stale NFS client
Getpwd: can't read
Both messages possibly means that your translator machine was rebooted and cannot determine the pathname to the current working directory. To reestablish the path, change directory and specify the complete pathname starting with /afs.
NFS server translator_machine is not responding still trying.
The NFS client is not getting a response from the NFS/AFS translator machine. If the NFS mount to the translator machine is a hard mount, your NFS client continues retrying the request until it gets a response (see Your NFS Client Machine is Frozen). If the NFS mount to the translator machine is a soft mount, the NFS client stops retrying after a certain number of attempts (three by default).
The AFS commands available to you are used to authenticate, list AFS information, protect directories, create and manage groups, and create and manage ACLs. There are three general types of commands available to all AFS users: file server commands, protection server commands, and miscellaneous commands. This chapter discusses the syntax of these AFS commands, the rules that must be followed when issuing them, and ways of accessing help relevant to them.
Most AFS commands use the following syntax:
command_suite operation_code -switch <value>[+] -flag
The command suite indicates the general type of command and the server process that performs the command. Regular AFS users have access to two main command suites and a miscellaneous set of commands:
The operation code indicates the action that the command performs. Miscellaneous commands have operation codes only.
A command can have multiple options, which can be arguments or flags:
In the following AFS command
% fs setacl -dir $HOME -acl pat all terry none -negative
This section describes the rules to follow when using AFS commands.
Separate each command element (command suite, operation code, switches, instances, and flags) with a space. Multiple instances of an argument are also separated by a space.
Type all AFS commands on one line, followed by a carriage return. Some commands in this document appear on more than one line, but that is for legibility only.
You can type operation codes in one of three ways:
For example, the fs listacl command can be issued as follows:
The IBM AFS Administration Reference provides information on the full and abbreviated command syntax as well as any aliases for all of the commands discussed in this guide.
You can omit an argument's switch if the command takes only one argument, or if the following conditions are met.
For example, the following two commands are equivalent:
% fs setacl -dir /afs/abc.com/usr/terry/private -acl pat rl % fs setacl /afs/abc.com/usr/terry/private pat rl
However, the following is not an acceptable short form because the arguments are not in the prescribed order:
% fs setacl -acl pat rl /afs/abc.com/usr/terry/private
If you are required to use a switch, or if you decide to use a flag, you can often shorten the name of that switch or flag provided that the shortened form still distinguishes it from the command's other flags and switches.
For example, when you issue the fs setacl command, you can abbreviate all of the switches and flags of the command to their initial letter because they all begin with a different letter. However, when you issue the knfs command, the -host argument and -help flag both begin with the letter h, so the shortest unambiguous abbreviations are -ho and -he respectively.
Most AFS command arguments that require directory or pathnames instances accept one or more of the following short forms:
For example, if the user terry wants to grant r (read) and l (lookup) permissions on his home directory to his manager pat, terry can issue the following command.
% fs setacl -dir $HOME -acl pat rl
If the current working directory is terry's home directory, he can issue the following command.
% fs setacl -dir . -acl pat rl
Both of the previous examples are acceptable short forms for the following command:
% fs setacl -dir /afs/abc.com/usr/terry -acl pat rl
This section provides additional information on the commonly used AFS fs and pts commands. For more detailed information, see the IBM AFS Administration Reference.
Some fs commands extend UNIX file system semantics by invoking file-related functions that UNIX does not provide (setting access control lists, for example). Other fs commands help you control the performance of the Cache Manager running on your local client machine.
All fs commands accept the optional -help flag. It has the same function as the fs help command: it prints a command's online help message on the screen. Do not provide other options at the same time as this flag. It overrides them, and the only effect of issuing the command is to display the help message.
The privilege required for issuing fs commands varies. The necessary privileges for the fs commands described in this guide include the following:
The pts command suite is the interface through which you can create protection groups and add members to them. System administrators who belong to a special system group called system:administrators group can manipulate any group, and also create the user and machine entries that can belong to groups. Users who do not belong to the system:administrators group can always list the information associated with the group entries they own, as well as their own user entries. Depending on the setting of an entry's privacy flags, regular users can sometimes access and manipulate group entries in certain ways.
All pts commands accept optional arguments and flags. They are listed in the command descriptions in the IBM AFS Administration Reference and are described here in detail:
AFS online help consists of basic syntax messages. The AFS distribution also includes help in HTML format which your system administrator can make available to you.
To display a brief description of a command, its syntax statement, and alias if any, use the help operation code. For example, to display the online help entry for the fs listacl command, enter the following command:
% fs help listacl fs listacl: list access control list aliases: la Usage: fs listacl [-path <dir/file path>+] [-id] [-if] [-help]
To display the syntax statement only, use the -help flag, which is available on most AFS commands. For example, to display the syntax statement for the fs setacl command, enter the following command:
% fs setacl -help Usage: fs setacl -dir <directory>+ -acl <access list entries>+ [-clear] [-negative] [-id] [-if] [-help]
To display a short description of all of a command suite's operation codes, issue the help operation code without any other arguments. For example, the fs help command displays a short description of every operation code in the fs command suite.
To display a list of the commands in a command suite that concern a certain type of object, provide a relevant keyword argument to the apropos operation code. For example, if you want to set an ACL but cannot remember which fs command to use, issue the following command:
% fs apropos set setacl: set access control list setcachesize: set cache size setcell: set cell status setclientaddrs: set client network interface addresses setquota: set volume quota setserverprefs: set file server ranks setvol: set volume status sysname: get/set sysname (i.e. @sys) value
The following message indicates that there are no commands whose names or descriptions include the keyword string you have provided:
Sorry, no commands found
Note: | If the keyword you provide has spaces in it, enclose it in double quotes (" "). |