Chapter 2. Issues in Cell Configuration and Administration

Table of Contents

Differences between AFS and UNIX: A Summary
Differences in File and Directory Protection
Differences in Authentication
Differences in the Semantics of Standard UNIX Commands
The AFS version of the fsck Command and inode-based fileservers
Creating Hard Links
AFS Implements Save on Close
Setuid Programs
Choosing a Cell Name
How to Set the Cell Name
Why Choosing the Appropriate Cell Name is Important
Participating in the AFS Global Namespace
What the Global Namespace Looks Like
Making Your Cell Visible to Others
Making Other Cells Visible in Your Cell
Granting and Denying Foreign Users Access to Your Cell
Configuring Your AFS Filespace
The Top /afs Level
The Second (Cellname) Level
The Third Level
Creating Volumes to Simplify Administration
Assigning Volume Names
Grouping Related Volumes on a Partition
When to Replicate Volumes
The Default Quota and ACL on a New Volume
Configuring Server Machines
Replicating the OpenAFS Administrative Databases
AFS Files on the Local Disk
Configuring Partitions to Store AFS Data
Monitoring, Rebooting and Automatic Process Restarts
Configuring Client Machines
Configuring the Local Disk
Enabling Access to Foreign Cells
Using the @sys Variable in Pathnames
Setting Server Preferences
Configuring AFS User Accounts
Choosing Usernames and Naming Other Account Components
Grouping Home Directories
Making a Backup Version of User Volumes Available
Creating Standard Files in New AFS Accounts
Using AFS Protection Groups
The Three System Groups
The Two Types of User-Defined Groups
Login and Authentication in AFS
Identifying AFS Tokens by PAG
Using an AFS-modified login Utility
Using Two-Step Login and Authentication
Obtaining, Displaying, and Discarding Tokens
Setting Default Token Lifetimes for Users
Changing Passwords
Imposing Restrictions on Passwords and Authentication Attempts
Support for Kerberos Authentication
Security and Authorization in AFS
Some Important Security Features
Three Types of Privilege
Authorization Checking versus Authentication
Improving Security in Your Cell
A More Detailed Look at Mutual Authentication
Backing Up AFS Data
Backup Volumes
The AFS Backup System
Accessing AFS through NFS

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 OpenAFS Administration.

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

Differences between AFS and UNIX: A Summary

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

Differences in File and Directory Protection

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

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

  • AFS ACLs use seven access permissions rather than the three UNIX mode bits. See The AFS ACL Permissions.

  • For directories, AFS ignores the UNIX mode bits. For files, AFS uses only the first set of mode bits (the owner bits), and their meaning interacts with permissions on the directory's ACL. See How AFS Interprets the UNIX Mode Bits.

  • A directory's ACL protects all of the files in a directory in the same manner. To apply a more restrictive set of AFS permissions to certain file, place it in directory with a different ACL. If a directory must contain files with different permissions, use symbolic links to point to files stored in directories with different ACLs.

  • Moving a file to a different directory changes its protection. See Differences Between UFS and AFS Data Protection.

  • An ACL can include about 20 entries granting different combinations of permissions to different users or groups, rather than only the three UNIX entities represented by the three sets of mode bits. See Differences Between UFS and AFS Data Protection.

  • You can designate an AFS file as write-only as in the UNIX file system, by setting only the w (write) mode bit. You cannot designate an AFS directory as write-only, because AFS ignores the mode bits on a directory. See How AFS Interprets the UNIX Mode Bits.

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

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

Differences in Authentication

Just as the AFS filespace is distinct from each machine's local file system, AFS authentication is separate from local login. This has two practical implications, which will already be familiar to users and system administrators who use Kerberos for authentication.

  • To access AFS files, users must log into the local machine as normal, obtain Kerberos tickets, and then obtain AFS tokens. This process can often be automated through the system authentication configuration so that the user logs into the system as normal and obtains Kerberos tickets and AFS tokens transparently. If you cannot or chose not to configure the system this way, your users must login and authenticate in separate steps, as detailed in the OpenAFS User Guide.

  • Passwords may be stored in two separate places: the Kerberos KDC and, optionally, each machine's local user database (/etc/passwd or equivalent) for the local system. A user's passwords in the two places can differ if desired.

Differences in the Semantics of Standard UNIX Commands

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

The chmod command

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

The chown command

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

The chgrp command

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

The groups and id commands

If the user's AFS tokens are associated with a process authentication group (PAG), the output of these commands may include one or two large numbers. These are artificial groups used by the OpenAFS Cache Manager to track the PAG on some platforms. Other platforms may use other methods, such as native kernel support for a PAG or a similar concept, in which case the large GIDs may not appear. To learn about PAGs, see Identifying AFS Tokens by PAG.

The ln command

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

The sshd daemon and ssh command

In order for a user to have access to files stored in AFS, that user needs to have Kerberos tickets and an AFS token on the system from which they're accessing AFS. This has an implication for users who log in remotely via protocols such as Secure Shell (SSH): that log-in process must create local Kerberos tickets and an AFS token on the system, or the user will have to separately authenticate to Kerberos and AFS after logging in.

The OpenSSH project provides an SSH client and server that uses the GSS-API protocol to pass Kerberos tickets between machines. With a suitable SSH client, this allows users to delegate their Kerberos tickets to the remote machine, and that machine to store those tickets and obtain AFS tokens as part of the log-in process.

The AFS version of the fsck Command and inode-based fileservers


This section on fsck advice only applies to the inode-based fileserver binaries. On servers using namei-based binaries, the vendor-supplied fsck can be used as normal.

If you are using AFS fileserver binaries compiled with the inode-based format, 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 OpenAFS Quick Start Guide 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 your AFS support provider, contact the OpenAFS mailing lists, or refer to the OpenAFS support web page for support options. It is sometimes possible to recover volume data from the lost+found directory. If the data is not recoverabled, then restoring from backup is recommended.


Running the fsck binary supplied by the operating system vendor on an fileserver using inode-based file storage will result in data corruption!

Creating Hard Links

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

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

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

AFS Implements Save on Close

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

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

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

Setuid Programs

The UNIX setuid bit is ignored by default for programs run from AFS, but can be enabled by the system administrator on a client machine. The fs setcell command determines whether setuid programs that originate in a particular cell can run on a given client machine. Running setuid binaries from AFS poses a security risk due to weaknesses in the integrity checks of the AFS protocol and should normally not be permitted. See Determining if a Client Can Run Setuid Programs.

Set the UNIX setuid bit only for files whose owner is UID 0 (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. Setting the UNIX setuid bit for files owned with a different UID will have unpredictable resuilts, since that UID will be interpreted as possibly different users on each AFS client machine.

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 chown command, or issue the chmod system call or the chmod command to set the setuid bit.