Administration Guide

Appendix A. Managing the NFS/AFS Translator

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.

Summary of Instructions

This chapter explains how to perform the following tasks by using the indicated commands:

Overview

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:

• Its AFS client functionality enables it to access the AFS filespace. The Cache Manager requests and caches files from AFS file server machines, and can even maintain tokens for NFS users, if you have made the configuration changes that enable NFS users to authenticate with AFS.

• Its NFS server functionality makes it possible for the translator machine to export the AFS filespace to NFS client machines. When a user on an NFS client machine mounts the translator machine's /afs directory (or one of its subdirectories, if that feature is enabled), access to AFS is immediate and transparent. The NFS client machine does not need to run any AFS software.

Enabling Unauthenticated or Authenticated AFS Access

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 configure the environment for unauthenticated access, the AFS File Server considers the NFS users to be the user anonymous. They can access only those AFS files and directories for which the access control list (ACL) extends the required permissions to the system:anyuser group. They can issue only those AFS commands that do not require privilege, and then only if their NFS client machine is a system type for which AFS binaries are available and accessible by the system:anyuser group. Such users presumably do not have AFS accounts.

• If you configure the environment for authenticated access, you must create entries in the AFS Authentication and Protection Databases for the NFS users. The authentication procedure they use depends on whether the NFS client machine is a supported system type (one for which AFS binaries are available):

  • If AFS binaries are available for the NFS client machine, NFS users can issue the klog command on the NFS client machine. They can access the filespace and issue AFS commands to the same extent as authenticated users working on AFS client machines.

  • If AFS binaries are not available for the NFS client machine, NFS users must establish a connection with the translator machine (using the telnet utility, for example) and then issue the klog and knfs commands on the translator machine to make its Cache Manager use the tokens correctly while users work on the NFS client. They can access the AFS filespace as authenticated users, but cannot issue AFS commands. For instructions, see Authenticating on Unsupported NFS Client Machines.

Setting the AFSSERVER and AFSCONF Environment Variables

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

The AFSSERVER variable designates the AFS client machine that performs two functions for NFS clients:

• It acts as the NFS client's remote executor by executing AFS-specific system calls on its behalf, such as those invoked by the klog and tokens commands and by many commands in the AFS suites.

• Its stores the tokens that NFS users obtain when they authenticate with AFS. This implies that the remote executor machine and the translator machine must be the same if the user needs authenticated access to AFS.

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 Variable

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.

Setting Values for the Variables

To learn the values of the AFSSERVER and AFSCONF variables, AFS command interpreters consult the following three sources in sequence:

1. The current command shell's environment variable definitions

2. The .AFSSERVER or .AFSCONF file in the issuer's home directory

3. The /.AFSSERVER or /.AFSCONF file in the NFS client machine's root (/) directory. If the client machine is diskless, its root directory can reside on an NFS server machine.

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

Delayed Writes for Files Saved on NFS Client Machines

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.

Configuring NFS/AFS Translator Machines

To act as an NFS/AFS translator machine, a machine must configured as follows:

• It must be an AFS client. Many system types supported as AFS clients can be translator machines. To learn about possible restrictions in a specific release of AFS, see the IBM AFS Release Notes.

• It must be an NFS server. The appropriate number of NFS server daemons (nfsd and others) depends on the anticipated NFS client load.

• It must export the local directory on which the AFS filespace is mounted, /afs by convention.

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.

Loading NFS and AFS Kernel Extensions

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.

Configuring the Translator Machine to Accept AFS 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.

Controlling Optional Translator Features

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.

• The -convert argument controls whether the second and third (group and other) sets of UNIX mode bits on an AFS file or directory being exported to NFS are set to match the first (owner) mode bits. By default, the mode bits are set to match.

  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.

• The -uidcheck argument controls whether tokens can be assigned to an NFS user whose local UID on the NFS client machine differs from the local UID associated with the tokens on the translator machine. By default, this is possible.

  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.

• The -submounts argument controls whether users on the NFS client can mount AFS directories other than the top-level /afs directory. By default, the translator does not permit these submounts.

  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.

To configure an NFS/AFS translator machine

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.

1. Become the local superuser root on the machine, if you are not already, by issuing the su command.

      % su root
      Password: root_password
   

2. Configure the NFS/AFS translator machine as an NFS server, if it is not already. Follow the instructions provided by your NFS supplier. The appropriate number of NFS server daemons (such as nfsd) depends on the number of potential NFS clients.

3. Configure the NFS/AFS translator machine as an AFS client, if it is not already. For the most predictable performance, the translator machine's local copies of the /usr/vice/etc/CellServDB and /usr/vice/etc/ThisCell files must be the same as on other client machines in the cell.

4. Modify the file that controls mounting of directories on the machine by remote NFS clients.

   • On systems that use the /etc/exports file, edit it to enable export of the /afs directory to NFS clients. You can list the names of specific NFS client machines if you want to provide access only to certain users. For a description of the file's format, see the NFS manual page for exports(5).

     The following example enables any NFS client machine to mount the machine's /afs, /usr, and /usr2 directories:

        /afs
        /usr
        /usr2
     

   • On system types that use the share command, edit the /etc/dfs/dfstab file or equivalent to include share instructions that enable remote mounts of the /afs directory. Most distributions include the binary as /usr/sbin/share. The following example commands enable remote mounts of the root ( / ) and /afs directories. To verify the correct syntax, consult the manual page for the share command.

        share -F nfs -o rw -d "root" /
        share -F nfs -o rw -d "afs gateway" /afs
     

5. Edit the machine's AFS initialization file to invoke the standard UNIX exportfs command after the afsd program runs. On some system types, the modifications you made in Step 4 are not enough to enable exporting the AFS filespace via the /afs directory, because the resulting configuration changes are made before the afsd program runs during machine initialization. Only after the afsd program runs does the /afs directory become the mount point for the entire AFS filespace; before, it is a local directory like any other.

6. Modify the afsd command in the AFS initialization file to include the -rmtsys flag.

   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
   

7. (Optional) Depending on the number of NFS clients you expect this machine to serve, it can be beneficial to add other arguments to the afsd command in the machine's initialization file, such as the -daemons argument to set the number of background daemons. See Administering Client Machines and the Cache Manager and the afsd reference page in the IBM AFS Administration Reference.

8. Reboot the machine. On many system types, the appropriate command is shutdown; consult your operating system administrator's guide.

      # shutdown appropriate_options
   

To disable or enable Translator functionality, or set optional features

1. Become the local superuser root on the machine, if you are not already, by issuing the su command.

      % su root
      Password: root_password
   

2. Issue the fs exportafs command.

      # fs exportafs nfs [-start {on | off}} ]  [-convert {on | off}]   
                         [-uidcheck {on | off}]   [-submounts {on | off}] 
   

   -start

   Disables translator functionality if the value is off or reenables it if the value is on. Omit this argument to display the current setting of all parameters set by this command.

   -convert

   Controls the setting of the second and third (group and other) sets of UNIX mode bits on AFS files and directories as exported to NFS clients If the value is on, they are set to match the owner mode bits. If the value is off, the bits are not changed. If this argument is omitted, the default value is on.

   -uidcheck

   Controls whether issuers of the knfs command can specify a value for its -id argument that does not match their AFS UID:

   • If the value is on, the value of the -id argument must match the issuer's local UID.

   • If the value is off, the issuer of the knfs command can use the -id argument to assign tokens to a user who has a different local UID on the NFS client machine, such as the local superuser root.

   If this argument is omitted, the default value is off.

   -submounts

   Controls whether the translator services an NFS mount of any directory in the AFS filespace other than the top-level /afs directory. If the value is on, such submounts are allowed. If the value is off, only mounts of the /afs directory are allowed. If this argument is omitted, the default value is off.

Configuring NFS Client Machines

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.

• It must NFS-mount a translator machine's /afs directory on a local directory, which by convention is also called /afs. The following instructions explain how to add the mount command to the NFS client machine's /etc/fstab file or equivalent.

  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.

• It must run an appropriate number of NFS client biod daemons, which improve performance by handling pre-reading and delayed writing. Most NFS vendors recommend running four such daemons, and most NFS initialization scripts start them automatically. Consult your NFS documentation.

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.

To configure an NFS client machine to access AFS

1. Become the local superuser root on the machine, if you are not already, by issuing the su command.

      % su root
      Password: root_password
   

2. Configure the machine as an NFS client machine, if it is not already. Follow the instructions provided by your NFS vendor. The number of NFS client (biod) daemons needs to be appropriate for the expected load on this machine. The usual recommended number is four.

3. Create a directory called /afs on the machine, if one does not already exist, to act as the mount point for the translator machine's /afs directory. It is acceptable to use other names, but doing so introduces the limitation discussed in the introduction to this section.

      # mkdir /afs
   

4. Modify the machine's file systems registry file (/etc/fstab or equivalent) to include a command that mounts a translator machine's /afs directory. To verify the correct syntax of the mount command, see the operating system's mount(5) manual page. The following example includes options that are appropriate on many system types.

      mount -o hard,intr,timeo=300  translator_machine:/afs /afs
   

   where

   hard

   Indicates that the NFS client retries NFS requests until the NFS server (translator machine) responds. When using the translator, file operations possibly take longer than with NFS alone, because they must also pass through the AFS Cache Manager. With a soft mount, a delayed response from the translator machine can cause the request to abort. Many NFS versions use hard mounts by default; if your version does not, it is best to add this option.

   intr

   Enables the user to use a keyboard interrupt signal (such as <Ctrl-c>) to break the mount when the translator machine is inaccessible. Include this option only if the hard option is used, in which case the connection does not automatically break off when a translator machine goes down.

   timeo

   Sets the maximum time (in tenths of seconds) the translator can take to respond to the NFS client's request before the client considers the request timed out. With a hard mount, setting this option to a high number like 300 reduces the number of error messages like the following, which are generated when the translator does not respond immediately.

      NFS server translator is not responding, still trying
   

   With a soft mount, it reduces the number of actual errors returned on timed-out requests.

   translator_machine

   Specifies the fully-qualified hostname of the translator machine whose /afs directory is to be mounted on the client machine's /afs directory.

   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.

5. (Optional) If appropriate, create the /.AFSSERVER file to set the AFSSERVER environment variable for all of the machine's users. For a discussion, see Setting the AFSSERVER and AFSCONF Environment Variables. Place a single line in the file, specifying the fully-qualified hostname of the translator machine that is to serve as the remote executor. To enable users to issue commands that handle tokens, it must be the machine named as translator_machine in Step 4.

6. (Optional) If appropriate, create the /.AFSCONF file to set the AFSCONF environment variable for all of the machine's users. For a discussion, see Setting the AFSSERVER and AFSCONF Environment Variables. Place a single line in the file, specifying 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.

Configuring User Accounts

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.

• To access AFS as authenticated users, they must of course authenticate with AFS, which requires an entry in the Protection and Authentication Databases.

• To create and store files, they need the required ACL permissions. If you are providing a home directory for storage of personal files, it is conventional to create a dedicated volume and mount it at the user's home directory location in the AFS filespace.

• To issue AFS commands, they must meet several additional requirements:

  • They must be working on an NFS client machine of a supported system type and from which the AFS command binaries are accessible.

  • Their command shell must define values for the AFSSERVER and AFSCONF environment variables, as described in Setting the AFSSERVER and AFSCONF Environment Variables. It is often simplest to define the variables by creating /.AFSSERVER and /.AFSCONF file in the NFS client machine's root directory, but you can also either set the variables in each user's shell initialization file (.cshrc or equivalent), or create files called .AFSSERVER and .AFSCONF in each user's home directory.

  • They must have an entry in the AFS Protection and Authentication Databases, so that they can authenticate if the command requires AFS privilege. Other commands instead require assuming the local root identity on the translator machine; for further discussion, see The AFSSERVER Variable.

  • Their PATH environment variable must include the pathname to the appropriate AFS binaries. If a user works on NFS client machines of different system types, include the @sys variable in the pathname rather than an actual system type name.

To configure a user account for issuing AFS commands

1. Create entries for the user in the Protection and Authentication Databases, or create a complete AFS account. See the instructions for account creation in Creating and Deleting User Accounts with the uss Command Suite or Administering User Accounts.

2. Modify the user's PATH environment variable to include the pathname of AFS binaries, such as /afs/cellname/sysname/usr/afsws/bin. If the user works on NFS client machines of different system types, considering replacing the specific sysname value with the @sys variable. The PATH variable is commonly defined in a login or shell initialization file (such as the .login or .cshrc file).

3. (Optional) Set the AFSSERVER and AFSCONF environment variables if appropriate. This is required if the NFS client machines on which the user works do not have the /.AFSSERVER and /.AFSCONF files in their root directories, or if you want user-specific values to override those settings.

   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.

4. If the pathname you defined in Step 2 includes the @sys variable, instruct users to check that their system name is defined correctly before they issue AFS commands. They issue the following command:

      % fs sysname
   

Authenticating on Unsupported NFS Client Machines

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.

To authenticate using the knfs command

1. Log on to the relevant translator machine, either on the console or remotely by using a program such as telnet.

2. Obtain tokens for every cell you wish to access while working on the NFS client. AFS-modified login utilities acquire a token for the translator machine's local cell by default; use klog command to obtain tokens for other cells if desired.

3. Issue the knfs command to create a credential structure in the translator machine's kernel memory for storing the tokens obtained in the previous step. Include the -id argument to associate the structure with a UID on the NFS client that differs from your local UID on the translator machine. This is possible unless the translator machine's administrator has enabled UID checking on the translator machine; see Controlling Optional Translator Features. If the NFS client machine is a supported system type and you wish to issue AFS commands on it, include the -sysname argument to specify its system type.

      % knfs -host <host name>  [-id <user ID (decimal)>]  [-sysname  <host's '@sys' value>]
   

   where

   -host

   Specifies the fully-qualified hostname of the NFS client machine on which you are working.

   -id

   Specifies a local UID number on the NFS client machine with which to associate the tokens, if different from your local UID on the translator machine. If this argument is omitted, the tokens are associated with an NFS UID that matches your local UID on the translator machine. In both cases, the NFS client software marks your AFS access requests with the NFS UID when it forwards them to the Cache Manager on the translator machine.

   -sysname

   Specifies the value that the local machine's remote executor daemon substitutes for the @sys variable in pathnames when executing AFS commands issued on the NFS client machine (which must be a supported system type).

   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
   

4. Close the connection to the translator machine (if desired) and work on the NFS client machine.

To display tokens using the knfs command

1. Log on to the relevant translator machine, either on the console or remotely by using a program such as telnet.

2. Issue the knfs command with the -tokens flag to display the tokens associated with either the NFS UID that matches your local UID on the translator machine or the NFS UID specified by the -id argument.

      % knfs -host <host name>  [-id <user ID (decimal)>] -tokens
   

   where

   -host

   Specifies the fully-qualified hostname of the NFS client machine on which you are working.

   -id

   Specifies the local UID on the NFS client machine for which to display tokens, if different from your local UID on the translator machine. If this argument is omitted, the tokens are for the NFS UID that matches your local UID on the translator machine.

   -tokens

   Displays the tokens.

3. Close the connection to the translator machine if desired.

To discard tokens using the knfs command

1. If you closed your connection to the translator machine after issuing the knfs command, reopen it.

2. Issue the knfs command with the -unlog flag.

      % knfs -host  <host name>  [-id <user ID (decimal)>]  -unlog
   

   where

   -host

   Specifies the fully-qualified hostname of the NFS client machine you are working on.

   -id

   Specifies the local UID number on the NFS client machine for which to discard the associated tokens, if different from your local UID on the translator machine. If this argument is omitted, the tokens associated with an NFS UID that matches your local UID on the translator machine are discarded.

   -unlog

   Discards the tokens.

3. If desired, close the connection to the translator machine.