Mounting Volumes

Mounting Volumes
	Chapter 5. Managing Volumes

Mount points make the contents of AFS volumes visible and accessible in the AFS filespace, as described in About Mounting Volumes. This section discusses in more detail how the Cache Manager handles mount points as it traverses the filespace. It describes the three types of mount points, their purposes, and how to distinguish between them, and provides instructions for creating, removing, and examining mount points.

The Rules of Mount Point Traversal

The Cache Manager observes three basic rules as it traverses the AFS filespace and encounters mount points:

Rule 1: Access Backup and Read-only Volumes When Specified
When the Cache Manager encounters a mount point that specifies a volume with either a .readonly or a .backup extension, it accesses that type of volume only. If a mount point does not have either a .backup or .readonly extension, the Cache Manager uses Rules 2 and 3.
For example, the Cache Manager never accesses the read/write version of a volume if the mount point names the backup version. If the specified version is inaccessible, the Cache Manager reports an error.
Rule 2: Follow the Read-only Path When Possible
If a mount point resides in a read-only volume and the volume that it references is replicated, the Cache Manager attempts to access a read-only copy of the volume; if the referenced volume is not replicated, the Cache Manager accesses the read/write copy. The Cache Manager is thus said to prefer a read-only path through the filespace, accessing read-only volumes when they are available.
The Cache Manager starts on the read-only path in the first place because it always accesses a read-only copy of the root.afs volume if it exists; the volume is mounted at the root of a cell's AFS filespace (named /afs by convention). That is, if the root.afs volume is replicated, the Cache Manager attempts to access a read-only copy of it rather than the read/write copy. This rule then keeps the Cache Manager on a read-only path as long as each successive volume is replicated. The implication is that both the root.afs and root.cell volumes must be replicated for the Cache Manager to access replicated volumes mounted below them in the AFS filespace. The volumes are conventionally mounted at the /afs and /afs/cellname directories, respectively.
Rule 3: Once on a Read/write Path, Stay There
If a mount point resides in a read/write volume and the volume name does not have a .readonly or a .backup extension, the Cache Manager attempts to access only the a read/write version of the volume. The access attempt fails with an error if the read/write version is inaccessible, even if a read-only version is accessible. In this situation the Cache Manager is said to be on a read/write path and cannot switch back to the read-only path unless mount point explicitly names a volume with a .readonly extension. (Cellular mount points are an important exception to this rule, as explained in the following discussion.

The Three Types of Mount Points

AFS uses three types of mount points, each appropriate for a different purpose because of how the Cache Manager handles them.

When the Cache Manager crosses a regular mount point, it obeys all three of the mount point traversal rules previously described.
AFS performs best when the vast majority of mount points in the filespace are regular, because the mount point traversal rules promote the most efficient use of both replicated and nonreplicated volumes. Because there are likely to be multiple read-only copies of a replicated volume, it makes sense for the Cache Manager to access one of them rather than the single read/write version, and the second rule leads it to do so. If a volume is not replicated, the third rule means that the Cache Manager still accesses the read/write volume when that is the only type available. In other words, a regular mount point does not force the Cache Manager always to access read-only volumes (it is explicitly not a "read-only mount point").
To create a regular mount point, use the fs mkmount command as described in To create a regular or read/write mount point.
Note
To enable the Cache Manager to access the read-only version of a replicated volume named by a regular mount point, all volumes that are mounted above it in the pathname must also be replicated. That is the only way the Cache Manager can stay on a read-only path to the target volume.
When the Cache Manager crosses a read/write mount point, it attempts to access only the volume version named in the mount point. If the volume name is the base (read/write) form, without a .readonly or .backup extension, the Cache Manager accesses the read/write version of the volume, even if it is replicated. In other words, the Cache Manager disregards the second mount point traversal rule when crossing a read/write mount point: it switches to the read/write path through the filespace.
It is conventional to create only one read/write mount point in a cell's filespace, using it to mount the cell's root.cell volume just below the AFS filespace root (by convention, /afs/.cellname). As indicated, it is conventional to place a period at the start of the read/write mount point's name (for example, /afs/.example.com). The period distinguishes the read/write mount point from the regular mount point for the root.cell volume at the same level. This is the only case in which it is conventional to create two mount points for the same volume. A desirable side effect of this naming convention for this read/write mount point is that it does not appear in the output of the UNIX ls command unless the -a flag is included, essentially hiding it from regular users who have no use for it.
The existence of a single read/write mount point at this point in the filespace provides access to the read/write version of every volume when necessary, because it puts the Cache Manager on a read/write path right at the top of the filespace. At the same time, the regular mount point for the root.cell volume puts the Cache Manager on a read-only path most of the time.
Using a read/write mount point for a read-only or backup volume is acceptable, but unnecessary. The first rule of mount point traversal already specifies that the Cache Manager accesses them if the volume name in a regular mount point has a .readonly or .backup extension.
To create a read/write mount point, use the -rw flag on the fs mkmount command as described in To create a regular or read/write mount point.
When the Cache Manager crosses a cellular mount point, it accesses the indicated volume in the specified cell, which is normally a foreign cell. (If the mount point does not name a cell along with the volume, the Cache Manager accesses the volume in the cell where the mount point resides.) When crossing a regular cellular mount point, the Cache Manager disregards the third mount point traversal rule. Instead, it accesses a read-only version of the volume if it is replicated, even if the volume that houses the mount point is read/write.
It is inappropriate to circumvent this behavior by creating a read/write cellular mount point, because traversing the read/write path imposes an unfair load on the foreign cell's file server machines. The File Server must issue a callback for each file fetched from the read/write volume, rather than single callback required for a read-only volume. In any case, only a cell's own administrators generally need to access the read/write versions of replicated volumes.
It is conventional to create cellular mount points only at the second level in a cell's filespace, using them to mount foreign cells' root.cell volumes just below the AFS filespace root (by convention, at /afs/foreign_cellname). The mount point enables local users to access the foreign cell's filespace, assuming they have the necessary permissions on the ACL of the volume's root directory and that there is an entry for the foreign cell in each local client machine's /usr/vice/etc/CellServDB file, as described in Maintaining Knowledge of Database Server Machines.
Creating cellular mount points at other levels in the filespace and mounting foreign volumes other than the root.cell volume is not generally appropriate. It can be confusing to users if the Cache Manager switches between cells at various points in a pathname.
To create a regular cellular mount point, use the -cell argument to specify the cell name, as described in To create a cellular mount point.

To examine a mount point, use the fs lsmount command as described in To display a mount point. The command's output uses distinct notation to identify regular, read/write, and cellular mount points. To remove a mount point, use the fs rmmount command as described in To remove a mount point.

Creating a mount point in a foreign cell

Creating a mount point in a foreign cell's filespace (as opposed to mounting a foreign volume in the local cell) is basically the same as creating a mount point in the local filespace. The differences are that the fs mkmount command's directory argument specifies a pathname in the foreign cell rather than the local cell, and you must have the required permissions on the ACL of the foreign directory where you are creating the mount point. The fs mkmount command's -cell argument always specifies the cell in which the volume resides, not the cell in which to create the mount point.

To display a mount point

Issue the fs lsmount command.
```
   % fs lsmount <directory>
```
where
ls
Is the shortest acceptable abbreviation of lsmount.
directory
Names the mount point to display.

If the specified directory is a mount point, the output is of the following form:

   'directory' is a mount point for volume 'volume name'

For a regular mount point, a number sign (#) precedes the volume name string, as in the following example command issued on a client machine in the example.com cell.

   % fs lsmount /afs/example.com/usr/terry
   '/afs/example.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 example.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/.example.com
   '/afs/.example.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 example.com cell.

   % fs lsmount /afs/example.org
   '/afs/example.org' is a mount point for volume '#example.org: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 example.com cell.

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

If the directory is not a mount point or is not in AFS, the output reads as follows.

   'directory' is not a mount point.

If the output is garbled, it is possible that the mount point has become corrupted in the local cache. Use the fs flushmount command as described in To flush one or more mount points. This forces the Cache Manager to refetch the mount point.

To create a regular or read/write mount point

Verify that you have the i( insert) and a( administer) permissions on the ACL of the directory where you are placing the mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.
```
   % fs listacl [<dir/file path>]
```
Issue the fs mkmount command to create the mount point. Include the -rw flag if creating a read/write mount point.
```
   % fs mkmount <directory> <volume name> [-rw]
```
where
mk
Is the shortest acceptable abbreviation for mkmount.
directory
Names the mount point to create. A file or directory with the same name cannot already exist. A partial pathname is interpreted relative to the current working directory.
Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create a new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the pathname's second level (for example, /afs/.example.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.
volume name
Specifies the volume's full name, including the .backup or .readonly extension for a backup or read-only volume, if appropriate.
-rw
Creates a read/write mount point.

To create a cellular mount point

Verify that you have the i( insert) and a( administer) permissions on the ACL of the directory where you are placing the mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.
```
   % fs listacl [<dir/file path>]
```
If you are mounting one or more foreign cells' root.cell volume at the second level in your filespace and your cell's root.afs volume is replicated, you must create a temporary mount point for the root.afs volume's read/write version in a directory on which the ACL grants you the i and a permissions. The following command creates a mount point called new_cells in your cell's /afs/.cellname directory (the entry point to the read/write path in your cell).
Substitute your cell's name for cellname.
```
   % cd /afs/.cellname
   % fs mkmount new_cells root.afs
   % cd new_cells
```
Issue the fs mkmount command with the -cell argument to create a cellular mount point. Repeat the command for each cellular mount point as required.
```
   % fs mkmount <directory> <volume name> -cell <cell name>
```
where
mk
Is the shortest acceptable abbreviation for mkmount.
directory
Names the mount point to create. A file or directory with the same name cannot already exist. A partial pathname is interpreted relative to the current working directory. If you are mounting a foreign cell's root.cell volume, the standard value for this argument is the cell's complete Internet domain name.
volume name
Specifies the volume's full name, usually root.cell for a cellular mount point.
-cell
Specifies the complete Internet domain name of the cell in which the volume resides.
If you performed the instructions in Step 2, issue the vos release command to release the new version of the root.afs volume to its read-only sites. (This command requires that you be listed in your cell's /usr/afs/etc/UserList file. If necessary, verify by issuing the bos listusers command, which is fully described in To display the users in the UserList file.)
Also issue the fs checkvolumes command to force the local Cache Manager to access the new replica of the root.afs volume. If desired, you can also remove the temporary new_cells mount point from the /afs/.cellname directory.
```
   % vos release root.afs
   % fs checkvolumes
   % cd /afs/.cellname
   % fs rmmount new_cells
```
For your users to access a newly mounted foreign cell, you must also create an entry for it in each client machine's local /usr/vice/etc/CellServDB file and either reboot the machine or use the fs newcell command to insert the entry directly into its kernel memory. See the instructions in Maintaining Knowledge of Database Server Machines.

To remove a mount point

Verify that you have the d( delete) permission on the ACL of the directory from which you are removing the mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.
```
   % fs listacl [<dir/file path>]
```
Members of the system:administrators group always implicitly have the a( administer) and by default also the l( lookup) permission on every ACL and can use the fs setacl command to grant other rights as necessary.
Issue the fs rmmount command to remove the mount point. The volume still exists, but its contents are inaccessible if this is the only mount point for it.
```
   % fs rmmount <directory>
```
where
rm
Is the shortest acceptable abbreviation of rmmount.
directory
Names the mount point to remove. A partial pathname is interpreted relative to the current working directory.
Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the pathname's second level (for example, /afs/.example.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 access volumes directly by volume ID

You can directly access volumes by volume IDs. This is only recommended for temporary access to a volume. For example, if you have recently restored a volume from a backup, you can use this syntax to quickly access the volume without mounting it.

This feature is available with Windows and Linux based cache managers by default. This feature is available with other Unix based cache managers when the dynamic root (-dynroot) and fake stat (-fakestat) modes are enabled.

Examples:

Windows: \\afs\example.com%root.cell - Access a read/write volume directly
Windows: \\afs\example.com#root.cell - Access a read-only volume directly
Unix: /afs/.:mount/example.com:root.cell - Access a read/write volume directly
Unix: /afs/.:mount/example.com:root.cell.readonly - Access a read-only volume directly
Unix: /afs/.:mount/example.com:root.cell.backup - Access a backup volume directly