Storing AFS Documents in AFS

The AFS distribution includes the following documents:

Note

OpenAFS Documentation is not currently provided with all distributions, but may be downloaded separately from the OpenAFS website

The OpenAFS Documentation Distribution has a directory 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 OpenAFS 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.

  1. Issue the vos create command to create a volume for storing the AFS documentation. Include the -maxquota argument to set an unlimited quota on the volume. This enables you to copy all of the appropriate files from the CD-ROM into the volume without exceeding the volume's quota.

    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 
    
  2. Issue the fs mkmount command to mount the new volume. Because the root.cell volume is replicated, you must precede the cellname with a period to specify the read/write mount point, as shown. Then issue the vos release command to release a new replica of the root.cell volume, and the fs checkvolumes command to force the local Cache Manager to access them.

       # fs mkmount -dir /afs/.cellname/afsdoc -vol afsdoc
       # vos release root.cell
       # fs checkvolumes
    
  3. Issue the fs setacl command to grant the rl permissions to the system:anyuser group on the new directory's ACL.

       # cd /afs/.cellname/afsdoc 
       # fs setacl  .  system:anyuser rl 
    
  4. Unpack the OpenAFS documentation distribution into the /tmp/afsdocs directory. You may use a different directory, in which case the location you use should be subsituted in the following examples. For instructions on unpacking the distribution, consult the documentation for your operating system's tar command.

  5. Copy the AFS documents in one or more formats from the unpacked distribution into subdirectories of the /afs/cellname/afsdoc directory. Repeat the commands for each format.

       # mkdir format_name
       # cd format_name
       # cp -rp /tmp/afsdocs/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).

  6. (Optional) If you believe it is helpful to your users to access the AFS documents in a certain format via a local disk directory, create /usr/afsdoc on the local disk as a symbolic link to the documentation directory in AFS (/afs/cellname/afsdoc/format_name).

       # 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.