Choosing a Cell Name

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

Your cell name must distinguish your cell from all others in the AFS global namespace. By convention, 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 Example Corporation cell and the Example Organization cell can have a home directory for the user pat, because the pathnames are distinct: /afs/example.com/usr/pat and /afs/example.org/usr/pat.

By convention, cell names follow the Domain Name System (DNS) conventions for domain names. If you are already an Internet site, then it is simplest and strongly recommended to choose your Internet domain name as the cell name.

If you are not an Internet site, it is best to choose a unique DNS-style name, particularly if you plan to connect to the Internet in the future. There are a few constraints on AFS cell names:

How to Set the Cell Name

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

For file server machines, the two files that record the cell name are the /usr/afs/etc/ThisCell and /usr/afs/etc/CellServDB files. As described more explicitly in the OpenAFS Quick Start Guide, 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 use the Update Server, it distributes its copy of the ThisCell and CellServDB files to additional server machines that you install. If you do not use the Update Server, the OpenAFS Quick Start Guide 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 (client machines can only have one default cell at a time and server machines can only belong to one cell at a time). If the machine is a file server, follow the complete set of instructions in the OpenAFS Quick Start Guide for configuring a new cell. If the machine is a client, all you need to do is change the files appropriately and reboot the machine. The next section explains further the negative consequences of changing the name of an existing cell.

To set the default cell name used by most AFS commands without changing the local /usr/vice/etc/ThisCell file, set the AFSCELL environment variable in the command shell. It is worth setting this variable if you need to complete significant administrative work in a foreign cell.

Note

The fs checkservers and fs mkmount commands do not use the AFSCELL variable. The fs checkservers command always defaults to the cell named in the ThisCell file, unless the -cell argument is used. The fs mkmount command defaults to the cell in which the parent directory of the new mount point resides.

Why Choosing the Appropriate Cell Name is Important

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

Another reason to choose the correct cell name early in the process of installing your cell is that the cell membership defined in each machine's ThisCell file affects the performance of many programs and processes running on the machine. For instance, AFS commands (fs, pts, and vos commands, for example) 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 or configured in DNS 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 normally determines the cell for which a user receives an AFS token when he or she logs in to a machine.

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 will cause many commands from the AFS suites to not work as expected.