Using the NFS Client

Introduction

In a cross-development environment, the Network File System (NFS) client support provided by the SAS/C Connectivity Support Library enables the SAS/C Debugger to communicate with the host workstation. This appendix provides the basic information necessary to use this NFS support. Additional information is contained in Appendix A, "Installing and Administering the NFS Client" on page 83 and SAS Technical Report C-113, SAS/C Connectivity Support Library, Release 1.00.

The NFS client feature provides flexibility in configuring NFS for each user. The degree of effort required to set up your configuration depends on the amount of support given by the system administration staff at your site.

For example, minimal user effort is required when the system administrators provide a centralized mount-configuration file and set up security-system definitions to allow automatic login. In this situation, users can begin specifying NFS filenames to application programs immediately. On the other hand, some sites may leave mounting files to the individual user. Lack of a RACF compatible security system might require that users issue an NFSLOGIN command at the beginning of each session. Even at sites where a centralized configuration has been set up, individual users with specialized access requirements may still develop their own configurations.

If your site management has already developed a configuration and makes it available to you automatically, perhaps with some instructions for using NFS at your site, you can bypass this section. Otherwise, you may need to use some of the commands and facilities described here.

Before using NFS to access remote files, you must understand two things:

Logging on to the NFS Network

NFS servers use a UNIX, or POSIX, file-permission system. This system gives each user a UID, a GID, and possibly several additional supplementary GIDs. Each file is assigned ownership by user identification number (UID) and by group identification number (GID). Permissions for the file are set based on whether the user desiring access is the owner (has the same UID as the file), is in the file's group (has a GID that matches the GID of the file), or is some other user. For each of these three categories (owner, group, and other) read, write, and execute permission can be assigned.

To access files using NFS, your session on MVS or CMS must acquire UID and GID numbers that correspond to some user on the NFS server network. You acquire these numbers by contacting a login server on the NFS network to ask permission to access files according to a username that is known to that server. In many cases, contact with the NFS login server can be automatic the first time you access an NFS file. In other cases, you must issue the NFSLOGIN command to effect the login.

The function of the login server is to check your identification and grant you access to the network. Once logged on, the login server functions as an NFS server and provides access to the files located on the machine on which it resides. At this point you may also use the network to access files controlled by other NFS servers on other machines.

If you have a RACF compatible security system running on your mainframe and your site administration has given you access to your NFS login server username, then the security system can vouch for you and no password is required. Note that the login server username is not necessarily the same as your MVS or CMS userid. If you do not have a security system, then you will need to enter your password during the login process.

In summary, the login process can involve three pieces of information:

The requirement for a password depends on whether a mainframe security system can provide authentication for login server usernames. If the NFS client software can determine the other two pieces of information, either by default or by environment variables, then automatic login is possible. Otherwise, the NFSLOGIN command must be used.

For example, if your NFS network is composed of UNIX machines, your UNIX username is comkzz, and your login server is a UNIX machine called byrd.unx, then the CSL NFS client software must contact byrd.unx and provide comkzz as the user name. If your MVS username is also COMKZZ (the same except for upper case), the mainframe security administrator has authorized you to use the comkzz username for NFS, and byrd.unx has been configured as the default login server at your site, then the NFS client library will log you in automatically the first time you try to use NFS.

If, on the other hand, your site does not have RACF, a password is required. In this case, you need to issue the NFSLOGIN command to enter your password. See "NFSLOGIN" on page 99 for details.

After the login processing has succeeded, your session receives a UID and one or more GIDs. These control your subsequent accesses to NFS files.

Accessing Remote File Systems

Logging on establishes UID and GID information. The next step is to mount the remote file systems that you want to access.

Because the SAS/C CSL NFS client feature runs totally within your user address space under MVS, or on a virtual machine under CMS, you must mount remote file systems before accessing NFS files. A number of facilities are provided to make this process as transparent as possible. Mounts can occur in three ways:

At sites with standardized configurations, a series of mounts may be provided automatically. In this case, you do not need to do additional work unless you want a different configuration.

Saving File-System Context

Assuming that you are doing the configuration yourself, one of the first things to decide is the duration of your mounts. That is, do you want mounts and directory changes from one program to be preserved for the next program that is run? Mounts and directory changes form a file system context that may be restricted to the execution of a particular program or may be shared serially by programs under TSO or CMS.

Not sharing context can be easier. NFS mounts are very fast and involve minimal processing on the server. The serial sharing of file system context is accomplished using the mnttab file. When only a few file systems are mounted, reissuing the mounts in each program can be faster than reading and writing the mnttab file.

Unfortunately, processing the mnttab file at program startup and shutdown adds noticeable delays to otherwise fast commands and programs. The NFS sample programs cd, pwd, and ls illustrate this. Overall NFS performance is much better when a single program does many operations. Sharing is required, however, if working directory changes are to be preserved from one program to the next. You should always save the file-system context when working with the SAS/C Debugger in a cross-development environment.

You specify serial sharing of file system context by setting the ETC_MNTTAB environment variable to the name of a file to contain the context. For example, under TSO, you might use the value TSO:ETC.MNTTAB. This creates a file tsoprefix.ETC.MNTTAB. Under TSO you set the value using the PUTENV command. Allocating a DDname of ETCMNTTB has the same effect under MVS batch and may be more convenient. Under CMS, you can set the value using GLOBALV commands with the CENV group. Refer to SAS/C Compiler and Library User's Guide, Fourth Edition and SAS/C Library Reference, Third Edition, Volume 1, for more information about using environment variables with the SAS/C Compiler.

You do not need to create the mnttab file yourself. The NFS client library will create it automatically. It will also be deleted each time you log in to the NFS server. Note that, unlike the conceptually similar UNIX /etc/mnttab file, this file has a binary format. It also contains information, notably the current working directory, that is held by the kernel in UNIX.

Finally, be aware that the mnttab file cannot be shared simultaneously by many programs. If you are managing multiple programs that use NFS concurrently, either set up multiple mnttab files or set them up not to save context at all.

To avoid serial sharing, do not set the environment variable. Be aware that in this case, the MOUNT command and the sample cd command appear to have no effect, because the changes that they request are not saved when they end. When not sharing file system context, you will normally invoke all your mounts with the fstab configuration file.

Setting Up an fstab Configuration File

When NFS starts with no mnttab file available, either because there is no serial sharing of file system context, or NFS has not yet been used, the NFS client library searches for an fstab configuration file from which to perform initial mounts. The fstab file removes the need to issue mount commands manually each time NFS is used.

The fstab configuration file format is identical to that used on most UNIX systems. It should have a series of lines that specify mount points using the following format:

 server : directory mount-point type options
Fields are separated by white space, and any fields that follow the options parameter are ignored. You can also include comments in the fstab configuration file. The pound (#) character at the beginning of a line or preceded by whitespace indicates that the rest of the line is a comment.

For NFS file systems, the device is specified as a server name followed by a colon (:), which is followed by the name of the directory to mount. This name must be a physical file on the server. It must not be a name that was created by NFS client features of the server. This is a common source of confusion. Users of the NFS server are often accustomed to specifying directory names that are not physical directories on their system. As discussed earlier, the design of NFS does not cause these names to be propagated automatically to NFS clients of that server.

The mount-point parameter must be a pathname in the directory hierarchy that is being created on the mainframe. In order for the first directory to be mounted, the mount point must be a slash (/), which indicates the root directory. Following NFS conventions, later mount points must be actual directories in a file system that have already been mounted. The directories that are being mounted then obscure the contents of the directory they are mounted on.

The type parameter must be nfs. As on UNIX, the table definition is generalized to accommodate multiple types of file systems; however, at present only NFS file systems are supported.

Mount options, which are described in "Mount Options" on page 95, generally are not needed.

The following example shows a typical fstab configuration file:

 # My NFS setup
 byrd.unx:/local/u/bill  /  nfs  #No mount options
 server.unx:/tools /tools nfs ro  # Mount tools read-only
 elgar.langdev:c:/ /lang nfs    # Mount from OS/2
This example assumes that the /local/u/bill directory on byrd.unx contains subdirectories called tools and lang. Presumably these are empty directories that were set up to serve as mount points for the second and third mounts. If they are not empty, any contents that they have are obscured to the mainframe user by the second and third mounts. Instead of seeing the contents of the local directories, the corresponding directory trees from the /tools directory on server.unx and the c:/ directory on elgar.langdev are seen by the mainframe user at those locations.

The fstab data set is located in the following manner:

  1. Under TSO, tsoprefix.ETC.FSTAB is used.
  2. Under MVS (other than TSO), if the userid can be determined, userid.ETC.FSTAB is used.
  3. Under CMS, ETC FSTAB is used.
The fstab data set cannot itself be accessed with the path: prefix. See "Accessing Files" on page 84 for information about the path: prefix.

Mount Options

Mount options control the operation of mounting the file system, as well as the file system's characteristics for subsequent use. They must be separated by commas, with no intervening spaces. They can be specified in either uppercase or lowercase. Mount options are not usually needed; the defaults are generally adequate.

The following options can be specified:

TABLE 26. Mount Options

------------------------------------------------------------------------------------------
| Option      | Description                                                              |
==========================================================================================
| RW          | Indicates that the file system is read/write. This is the default        |
|             | setting.                                                                 |
------------------------------------------------------------------------------------------
| RO          | Indicates that the file system is read-only.                             |
------------------------------------------------------------------------------------------
| DELTAMIN    | Indicates the time adjustment in minutes to be applied to time           |
|             | stamps on the given file system. This can be useful when file            |
|             | systems are set to operate in different time zones. This value can be    |
|             | either positive or negative.                                             |
------------------------------------------------------------------------------------------
| RETRY=n     | Number of retries for mount failures. The default is 1. The              |
|             | parameter affects only mount attempts. It does not affect other          |
|             | operations such as read and write. (See RETRANS for other                |
|             | operations.)                                                             |
------------------------------------------------------------------------------------------
| RWSIZE=nnK  | Read and write buffer size. The default is 4K. The maximum               |
|             | allowed is 1024K.                                                        |
------------------------------------------------------------------------------------------
| TIMEO=n     | Controls the timeout interval in tenths of a second used between         |
|             | retransmission attempts. The actual timeout interval begins at n         |
|             | tenths of a second and is doubled for each retransmission. The           |
|             | default TIMEO value is 7. (See also RETRANS.)                            |
------------------------------------------------------------------------------------------
| RETRANS=n   | Specifies the number of NFS retransmissions. The default is 4. The       |
|             | timeout is multiplied by 2 for each successive retransmission.           |
------------------------------------------------------------------------------------------
| SOFT        | Specifies that a transmission attempt should be abandoned after a        |
|             | complete set of retransmissions fails. This is the default.              |
------------------------------------------------------------------------------------------
| HARD        | Specifies that a transmission attempt should not be abandoned after      |
|             | a complete set of retransmissions fails. If HARD is specified, the       |
|             | retransmission process is started over again after each set of           |
|             | transmissions is completed.                                              |
------------------------------------------------------------------------------------------
| TEXT        | Perform ASCII or EBCDIC translation on all files. An                     |
|             | ASCII-to-EBCDIC translation is performed when the file is read           |
|             | from the server, and an EBCDIC-to-ASCII translation is performed         |
|             | when the file is written to the server.                                  |
------------------------------------------------------------------------------------------
| BINARY      | Always leave data in untranslated, binary form.                          |
------------------------------------------------------------------------------------------
| XLATE       | The name of a loadable translate table to be used for ASCII and          |
|             | EBCDIC translation in this file system. This translation affects data    |
|             | that are read and written. By default, NFS data are translated using     |
|             | the IBM code page 1047 standard. The table is built in much the          |
|             | same manner as SAS/C CSL RPC translate tables. (Refer to the             |
|             | description of the xdr_string function in SAS Technical Report           |
|             | C-113, SAS/C Connectivity Support Library, Release 1.00) The             |
|             | only difference is that you may choose any load module name and          |
|             | then specify it here. If you have created an L$NAEXDR table for          |
|             | RPC, you may specify it to get the same translations for NFS data        |
|             | as for RPC strings. The XLATE option does not affect pathnames,          |
|             | which are controlled by the RPC L$NAEXDR translate table if              |
|             | present. If the translate table is not present, use the code page 1047   |
|             | standard.                                                                |
------------------------------------------------------------------------------------------

The TEXT and BINARY mount options allow you to override the defaults, which are determined by the debugger when it accesses a file on the workstation. However, we recommend using them only in unusual situations. When using the SAS/C Debugger, the settings defined by the debugger are generally appropriate.

Mounting and Unmounting Manually

When you are saving your file system context between programs, you can manipulate your file system organization by using the MOUNT and UMOUNT commands. These commands are described later in this chapter.

Manipulating Files and Directories

Once you are logged in and have the remote file systems mounted into the directory structure that you want, you can begin to access files. In many cases you can do this through SAS/C programs that are not aware of NFS simply by specifying path: where you previously specified a local file name. This will work if the particular program that you are using allowed you to specify the style prefix. For example, CMS programs that let you access CMS Shared File System files using the sf: prefix will now allow you to access NFS file using the path: prefix. If the program uses the correct setting for text or binary processing when it opens files, text files will be translated from ASCII to EBCDIC automatically. If it does not, you can use the TEXT and BINARY mount options to override the program's decision.

Existing SAS/C programs can also remove, rename, and check accessibility of NFS files.

If you are not saving file system context, or if you are, but haven't run a program to change the initial directory, you must use the full pathname (from the mainframe point of view) in order to access a file.

Programs that were developed using SAS/C CSL can access and manipulate the remote file systems more completely. They can create, delete, and list directories. They can work with hard and symbolic links. They can change or check the current working directory, and they can retrieve and change UNIX, or POSIX, file-status information.

The SAS/C CSL product contains many sample programs which can also be used as simple utilities. For example, there is a simple ls command that lists the files in a directory. There is an ncp command that can copy files between mainframe file systems and NFS file systems (and can be much quicker than getting into FTP). These are simple sample programs. They do not have the full features of their UNIX equivalents, but they are useful.

The following examples are distributed with the CSL run-time transients provided with the SAS/C Cross-Platform Compiler:

TABLE 27. Sample Programs

-----------------------------------------------------
| Example  | Description                            |
=====================================================
| cd       | Change the directory (requires an      |
|          | ETC_MNTTAB setting)                    |
-----------------------------------------------------
| ls       | List a directory (no wildcards)        |
-----------------------------------------------------
| ncp      | Copy files between mainframe and NFS   |
|          | file systems                           |
-----------------------------------------------------
| pwd      | Print the working directory            |
-----------------------------------------------------

NFS User Commands

The following commands are used primarily by users who are running NFS client applications:

TABLE 28. NFS User Commands

-------------------------------------------------------------
| Command   | Description                                   |
=============================================================
| NFSLOGIN  | Authorizes TSO or CMS users to access files   |
|           | via NFS.                                      |
-------------------------------------------------------------
| MOUNT     | Mounts remote NFS file systems into the NFS   |
|           | client file system structure.                 |
-------------------------------------------------------------
| UMOUNT    | Removes a previously established mount.       |
-------------------------------------------------------------

The format used to invoke the NFSLOGIN, MOUNT, and UMOUNT commands is generally identical to that shown in the following reference information. On MVS, system administration considerations may require use of the TSO CALL command or other techniques. See your system administrator for details. Reference information for each of these commands is given on pages 98, 99, and 101.

MOUNT

Mounts remote NFS file systems into the NFS client file system structure

SYNOPSIS

Format 1: MOUNT server :directory mount-point [options]

DESCRIPTION

The MOUNT command is one method of mounting remote NFS file systems into the NFS client file system structure on the mainframe. This command is useful only when you have configured your session to save file system context. Otherwise, the effect of the mount disappears when the MOUNT command completes.

The server parameter specifies the name of the NFS server on which the files are physically located. The directory is the name of the directory for the directory tree that you want to mount. It must be a physical filename on that server (it cannot be created by the server's NFS client software).

The mount-point parameter specifies the name of the mainframe NFS client directory on which the remote file system is to be mounted. For the first mount, this must be a slash (/). For subsequent mounts, it must be a valid pathname in the directory structure established by existing mounts.

The options string is not required. It specifies mount options for the file system. See "Mount Options" on page 95. The string of options must be separated by commas, with no intervening spaces.

You cannot mount on a directory that is already being used as a mount point. You must first unmount the existing file system with the UMOUNT command.

Be aware that mounts made by this command are preceded by mounts from any fstab file.

EXAMPLES

These examples assume that there is no fstab file and that file system context is being saved.

 mount byrd.unx:/local/u/bill /
Mount bill's home directory on "byrd.unx" as the root directory on the mainframe.

 mount server.unx:/tools /tools ro 
Add the /tools directory from server.unx as a subdirectory and treat it as read-only.

NFSLOGIN

Authorizes TSO or CMS users to access files via NFS

SYNOPSIS

Format 1: NFSLOGIN [-s server] [-u username] [-p password] [-n]

Format 2: NFSLOGIN -f

DESCRIPTION

The NFSLOGIN command authorizes TSO or CMS users to access files via NFS. In some cases the NFS client software can determine the correct server and username without you specifying them. If a RACF compatible security system is installed, the site can define particular mainframe users as having access to specified UNIX userids without requiring a password. If no password is required, and if the other values are correct by default, you do not need to use this command. The login will occur automatically when you access the first NFS file or directory.

The NFSLOGIN command is provided for sites and situations where either a password is needed or the default server or username values must be overridden.

See "Logging on to the NFS Network" on page 91 for an introductory discussion of NFS login considerations. Also see "NFS Security Administration" on page 86 and the description of the nfslogin function in SAS Technical Report C-113, SAS/C Connectivity Support Library, Release 1.00 for more detailed information.

The -f option requests a full-screen display. This display has fields for entering the same information that can be specified on the command line. The full-screen option provides non-display password entry.

The server parameter is the host name of the login server that you want to contact. This may differ from the servers on which files are being accessed. The specified host must be running the appropriate login server software. See Appendix A, "Installing and Administering the NFS Client" on page 83 for details. You can usually omit this option because the site can set up a default at installation time. Note also that, when a security system is installed, the mainframe security administrator controls your access to login servers. Using an unauthorized server causes a RACF violation.

For username, enter your username on the NFS login server. This is often different from your MVS or CMS login ID. You do not need to specify a username if the USER environment variable is set to the desired name, or if your login server username is the same as your mainframe userid converted to lower case.

If you do not have a RACF compatible security system, or if you want to login as a username that is not associated with your RACF profile, use the -p option or the password field to specify your password on the login server. The mainframe security system (if present) can also control whether a password will or will not be allowed on your NFSLOGIN.

Note that the -p option requires a value. The -n option is required for the special case where the UNIX (or other login server operating system) system account has a null password. The -p and -n options are mutually exclusive. Not specifying either -p or -n indicates that the user expects the mainframe security system to authorize access to the login server username. The full-screen display also allows for the special case of a null password.

If the login attempt fails, NFSLOGIN prints a message describing the reason. Otherwise it prints a message indicating success. The login fails if the login server is not running on the NFS network.

Note that you don't need to log out from the login server; your UID and GID permissions will expire after you log off of TSO or CMS. If you want to access files under a different user name, you can issue NFSLOGIN again. A login will expire after two days. If you are connected to a session for several days, you will need to log in again.

EXAMPLES

 nfslogin -f 
Invoke the full-screen login panel.

 nfslogin -u bbritten -p ocean 
Log in to the default login server with username bbritten and password ocean.

UMOUNT

Removes a previously established mount

SYNOPSIS

Format 1: UMOUNT mount-point

DESCRIPTON

The UMOUNT command removes a previously established mount. This command is useful only when you have configured your session to save file system context. Otherwise, the effect of the unmount disappears when the UMOUNT command completes.

The mount-point parameter specifies a mainframe pathname to a directory from which a remote file system will be unmounted. The directory must have been used in a previous mount operation.

You cannot unmount the root directory. If you want to mount a totally different root directory, delete the mnttab file and then mount the new root directory. NFSLOGIN also deletes the mnttab file.

You cannot unmount a file system that has other directories mounted over it, or a file system containing your current directory. Attempting to do so results in the following message:

 UMOUNT failed: file or record in use.

EXAMPLE

This example assumes that file system context is being saved.

 umount /tools 
Remove the file system that was previously mounted at /tools. If the file system mounted at / had any files in its tools subdirectory, these now become visible.