File Access Applications

11.3 NFS

The I/O driver nfsDrv, which provides NFS client support, uses the client routines in the library nfsLib to access files on an NFS file server.

VxWorks also allows you to run an NFS server to export files to other systems. The server task mountd allows other systems on the network to mount VxWorks file systems (dosFs only); then the server task nfsd allows them to read and write to those files. The VxWorks NFS server facilities are implemented in the following libraries:

mountLib

Mount Protocol library. Provides functions to manage exporting file systems.

nfsdLib

NFS Server library. Provides functions to manage requests from remote NFS clients.

The routines in the VxWorks NFS libraries are implemented using RPC. For more information, see the reference entries for these libraries and RPC: Remote Procedure Calls.

11.3.1 VxWorks Target as Client

To access files on UNIX, NFS clients mount file systems from NFS servers. On a UNIX NFS server, the file /etc/exports specifies which of the server's file systems can be mounted by NFS clients. For example, if /etc/exports contains the following line:

/usr

then the file system /usr can be mounted by NFS clients such as VxWorks. If a file system is not listed in this file, it cannot be mounted by other machines. Other optional fields in /etc/exports allow the exported file system to be restricted to certain machines or users.

CAUTION: On Windows, most networking packages that support NFS also supply a mechanism for exporting files so that they are visible on the network. See your Windows and networking software documentation for information on this facility.

Creating VxWorks Network Devices that Use NFS

Access to a remote NFS file system is established by mounting that file system locally and creating an I/O device for it using the routine nfsMount( ):

nfsMount ("host", "hostFileSys", "localName")

Its arguments are:

host

The host name of the NFS server where the file system resides.

hostFileSys

The name of the desired host file system or subdirectory.

localName

The local name to assign to the file system.

For example, the following call mounts /usr of the host mars as /vwusr locally:

-> nfsMount "mars", "/usr", "/vwusr"

The host name mars must already be in VxWorks's list of hosts (added with the routine hostAdd( )). VxWorks then creates a local I/O device /vwusr that refers to the mounted file system. A reference on VxWorks to a file with the name /vwusr/darger/myfile refers to the file /usr/darger/myfile on the host mars as if it were local to the VxWorks system.

If VxWorks is configured with "NFS mount all" on, VxWorks mounts all host-exported NFS file systems. The relevant configuration macro is INCLUDE_NFS_MOUNT_ALL. Otherwise, the network startup routine, usrNetInit( ) in usrNetwork.c, tries to mount the file system from which VxWorks was booted--as long as NFS is included in the VxWorks configuration and the VxWorks boot file begins with a slash (/). For example, if NFS is included and you boot /usr/wind/target/config/bspname/vxWorks, then VxWorks attempts to mount /usr from the boot host with NFS.

Setting the User ID for Remote File Access with NFS

When making an NFS request to a host system, the NFS server expects more information than the user's name. NFS is built on top of Remote Procedure Call (RPC) and uses a type of RPC authentication known as AUTH_UNIX. This mechanism requires the user ID and a list of group IDs to which the user belongs. These parameters can be set on VxWorks using nfsAuthUnixSet( ). For example, to set the user ID to 1000 and the group ID to 200 for the machine mars, use:

-> nfsAuthUnixSet "mars", 1000, 200, 0

The routine nfsAuthUnixPrompt( ) provides a more interactive way of setting the NFS authentication parameters from the Tornado shell. On UNIX systems, a user ID is specified in the file /etc/passwd. A list of groups that a user belongs to is specified in the file /etc/group.

A default user ID and group ID is specified during configuration by setting the user identifier for NFS access (the configuration constant NFS_USER_ID, set by default to 2001) and the group identifier for NFS access (the configuration constant NFS_GROUP_ID, set by default to 100) respectively. The NFS authentication parameters are set to these values at system startup. If NFS file access is unsuccessful, make sure that the configuration is correct.

11.3.2 VxWorks Target as Server

To export a dosFs file system with NFS, carry out the following steps:

Initialize a dosFs file system, with the option that makes it NFS-exportable.

To use the file system from another machine after you export it, you must also:

Mount the remote VxWorks file system using local host facilities.

To include NFS Server support, reconfigure VxWorks. The relevant configuration macro is INCLUDE_NFS_SERVER. If you wish, you can run a VxWorks system with only NFS Server support (no client support).

Initializing an NFS-Exportable File System

To export a dosFs file system with NFS, you must initialize that file system with the DOS_OPT_EXPORT option (see VxWorks Programmer' Guide: Volume Configuration). With this option, the dosFs initialization code creates some small additional in-memory data structures; these structures make the file system exportable.

The following steps initialize a DOS file system called /export on a SCSI drive. You can use any block device instead of SCSI. Your BSP can also support other suitable device drivers; see your BSP's documentation.

Initialize the block device containing your file system.

For example, you can use a SCSI drive as follows:

scsiAutoConfig (NULL); 
pPhysDev = scsiPhysDevIdGet (NULL, 1, 0); 
pBlkDev = scsiBlkDevCreate (pPhysDev, 0, 0);

Calling scsiAutoConfig( ) configures all SCSI devices connected to the default system controller. (Real applications often use scsiPhysDevCreate( )instead, to specify an explicit configuration for particular devices.) The scsiPhysDevIdGet( ) call identifies the SCSI drive by specifying the SCSI controller (NULL specifies the default controller), the bus ID (1), and the Logical Unit Number (0). The call to scsiBlkDevCreate( ) initializes the data structures to manage that particular drive.

Initialize the file system with the usual dosFs facilities, but also specify the option DOS_OPT_EXPORT. If your NFS client is PC-based, it may also require the DOS_OPT_LOWERCASE option. For example, if the device already has a valid dosFs file system on it (see VxWorks Programmer's Guide: Using an Already Initialized Disk), initialize it as follows:

dosFsDevInitOptionsSet (DOS_OPT_EXPORT); 
dosFsDevInit ("/export", pBlkDev, NULL);

Otherwise, specify a pointer to a DOS_VOL_CONFIG structure rather than NULL as the third argument to dosFsDevInit( )(see the dosFsLib reference entry for details).

CAUTION: For NFS-exportable file systems, the device name must not end in a slash.

Exporting a File System through NFS

After you have an exportable file system, call nfsExport( )to make it available to NFS clients on your network. Then mount the file system from the remote NFS client, using the facilities of that system. The following example shows how to export the new dosFs file system from a VxWorks platform called vxTarget, and how to mount it from a typical UNIX system.

After the file system (/export in this example) is initialized, the following function call specifies it as a file system to be exported with NFS:

nfsExport ("/export", 0, FALSE, 0);

The first three arguments specify the name of the file system to export; the VxWorks NFS export ID (0 means to assign one automatically); and whether to export the file system as read-only. The last argument is a place-holder for future extensions.

To mount the file system from another machine, see the system documentation for that machine. Specify the name of the VxWorks system that exports the file system, and the name of the desired file system. You can also specify a different name for the file system as seen on the NFS client.

CAUTION: On UNIX systems, you normally need root access to mount file systems.

For example, on a typical UNIX system, the following command (executed with root privilege) mounts the /export file system from the VxWorks system vxTarget, using the name /mnt for it on UNIX:

# /etc/mount vxTarget:/export /mnt

Properties of NFS-Exported File Systems

Several global variables allow you to specify dosFs facilities related to NFS support. Because these facilities use global variables, you can export previously existing dosFs file systems without altering the existing configuration stored with the file system data on disk.

However, because these are global variables, you must take care to avoid race conditions if more than one task initializes dosFs file systems. If your application initializes file systems for NFS on the fly, you may need mutual exclusion surrounding these global variable settings and the corresponding file system initialization.

You can specify a single user ID, group ID, and mode (permissions) for all files within a dosFs file system. To specify these values, define the following global variables before initializing a dosFs file system with either dosFsDevInit( ) or dosFsMkfs( ):

dosFsUserId

Numeric user ID. Default: 65534.

dosFsGroupId

Numeric group ID. Default: 65534.

dosFsFileMode

Numeric file access mode (that is, permissions with UNIX encoding). Default: 511 (octal, 777).

These settings remain in effect for the file system until you reboot.

WARNING: dosFsFileMode controls only how the file access mode is reported to NFS clients; it does not override local access restrictions on the DOS file system. In particular, if any file in an exported file system has DOS_ATTR_RDONLY set in its file-attribute byte, no modifications to that file are permitted regardless of what dosFsFileMode says.

You can also set the current date and time for the DOS file system using dosFsDateSet( )and dosFsTimeSet( ). For a discussion of these routines and other standard dosFs facilities, see VxWorks Programmer's Guide: MS-DOS-Compatible File System: dosFs.

Limitations of the VxWorks NFS Server

The VxWorks NFS Server can export only dosFs file systems, which leads to the following DOS limitations:

File names in dosFs normally share the DOS limit of 8 characters with a three-character extension. An optional dosFs feature allows (at the expense of DOS compatibility) file names up to forty characters long. To enable this extension, create the file system with the DOS_OPT_LONGNAMES option (defined in dosFsLib.h).

DOS file systems do not provide for permissions, user IDs, and group IDs on individual files. You can provide a single user ID, a single group ID, and a single set of permissions for all files on an entire DOS file system by defining the global variables dosFsUserId, dosFsGroupId, and dosFsFileMode, described in the reference entry for dosFsLib.

Because the DOS file system does not provide file permissions, VxWorks does not normally provide authentication services for NFS requests. To authenticate incoming requests, write your own authentication functions and arrange to call them when needed. See the reference entries for nfsdInit( ) and mountdInit( ) for information on authorization hooks.