WebNFS Developer's Guide

Appendix A Frequently Asked Questions

Overview

This appendix covers the following questions:

The WebNFS and Extended Filesystem API FAQ

Answers to some commonly asked questions about WebNFS:

Why Do I Get "Permission Denied" Errors When I Try to Read My Own Files?

The Java NFS client defaults the user's credential to nobody, that is, a user-id and group-id of 60001. This identity is fine if the user is accessing files in a public archive, but if the files have access restrictions enforced by the file permissions then access will be denied unless a valid credential is used. The class XFileExtensionAccessor in com.sun.nfs supports a method called loginPCNFSD() that passes the user's login name and password to the PCNFSD service on a server that is running the PCNFSD daemon. If the loginname and password are correct then a valid credential with the user's UID and GID is constructed and used in all future NFS calls.

When I Create a File Or Directory over NFS, Why Is It Owned by `nobody`?

You are using the default credential. You need to obtain a valid credential for your loginname and password so that the server can identify you as the owner of the file. (See previous question.)

Why Won't My NFS URL Work with a Non-WebNFS Server?

If the Java NFS client cannot evaluate the URL using the WebNFS technique, it will fall back to using the MOUNT protocol. While WebNFS paths are evaluated relative to the directory associated with a public filehandle, MOUNT paths are absolute. For UNIX servers this means that the path must start with a slash. The slash in the NFS URL that separates the server name from the pathname is not considered to be a part of the pathname. To have the pathname begin with a slash you need to add a second slash, e.g. if mounting /export/home from the non-WebNFS server dopey you use the following path:

 nfs://dopey//export/home

Can I Use an NFS Proxy Server?

No, not directly. The HTTP protocol is designed for proxy use, but protocols like FTP and NFS cannot be proxied directly; that is. you cannot send an NFS request to a proxy server with instructions to forward the request to (and reply from) another NFS server. However, as with FTP, NFS can be proxied by an NFS-capable HTTP proxy server if you need to be able to browse directories graphically or transfer files.

How Do I Access an Internet NFS Server Through My Firewall?

If the NFS server supports WebNFS and TCP connections for NFS, then have your firewall administrator provide access for outgoing connections to port 2049. If the server does not support WebNFS, then access will be much difficult since the client will have to use the MOUNT protocol to obtain an initial filehandle; however, this protocol does not use a "well-known" port. This makes it almost impossible to configure the firewall to allow NFS mounts unless the firewall software supports some kind of portmap protocol snooping.

Why Can't I Access Files on a Digital UNIX Server?

If the server doesn't support WebNFS then the client will use the MOUNT protocol. Some mount daemons will reject mount requests if they come from a client that cannot be resolved through a reverse DNS lookup or if the client is using an unprivileged source port (not less than or equal to1024). Digital Unix server administrators should check the settings of the mountd's -i and -n options.

How Do I Browse the Exported Filesystems of a Server?

If you have a URL to an exported filesystem, you can browse the exported filesystem by listing directories and subdirectories. However, if you want to discover the exported filesystems on an NFS server, only the MOUNT protocol can do that. On UNIX clients you can use the showmount or dfshare" commands to obtain a list of exported filesystems from an NFS server.

How Can I Tell If a File Is "Hidden"?

XFile has no method to determine the "hiddenness: of a file; that is, there is no isHidden() method. It is difficult to implement for native filesystems because java.io.* provides no access to the "hidden" bit on DOS/Windows filesystems. NFS clients typically recognize hidden files using the UNIX convention of an initial dot in the name, though this is just a convention and not supported directly by the NFS protocol. In summary, there is no way to tell if a DOS/Windows file is hidden, but an initial dot is a clue to the "hiddenness" of a UNIX file.

What Kind of Cacheing Does the Java NFS Client Use?

Its cache model is quite similar to other NFS client implementations. File and directory data are cached from between 3 and 30 seconds, depending on the frequency of file or directory modification. That is, if the file is being changed every 10 seconds then the cache time will be set to 10 seconds, but if the file or directory hasn't changed for 6 months then it'll be cached for up to 30 seconds. When the cache time expires, the client will revalidate the cached data via a GETATTR request to the server. If the file or directory on the server is changed, then the cached copy is invalidated. The client uses the attributes returned by NFS v3 READ, WRITE, and LOOKUP calls avoiding unnecessary GETATTR revalidations.

To avoid hogging the JVM heap, the client avoids aggressive caching of file data. Only the current, read-ahead or write-behind buffers are cached. This has no impact on sequential file access, but could cause performance problems for applications that frequently re-read files exceeding a buffer in size (8k for v2, 32k for v3). The list of names in an NFS directory is cached when the directory is first read. If the server is read using NFS version 3 then the client will use the READDIRPLUS request and obtain the filehandles and attributes of all the directory entries. Note that a file tree walk or other procedure that touches lots of NFS files will eventually run the client out of memory. This memory limitation will be fixed in future versions of the client.

Using `XFileOutputStream`, I Write Data, But It Never Appears in the File. Why?

This is probably due to the write buffering. When you write data to an NFS server using XRandomAccessFile or XFileOutputStream the writes are buffered. When the buffer becomes full (NFS v2 8k, NFS v3 32k) the data is written to the server. If the Java application exits without calling the close() method then the last incomplete buffer will not be written to the server. It is important to call close() when you have finished writing data to a file!

How Do I Create or Read Symbolic Links?

The XFile API does not support symbolic links and the NFS ExtensionAccessor does not yet provide any methods that allow symbolic links to be read or created. The Java NFS client automatically follows symbolic links so that a URL that references a symbolic link will eventually result in a reference to a file or directory. The Java NFS client will correctly evaluate a symbolic link that contain an NFS URL. Note that the client does not yet detect symbolic link loops - a stack overflow will result if a symlink loop is entered.

Can I Detect a Symbolic Link?

No. Any reference to a symbolic link will cause it to be followed and the attributes of the link destination will be returned. A future release of the NFS client will add the ability to detect symbolic links to the NFS ExtensionAccessor.

Can I Control the Client's Read Size and Write Size?

Most client implementations of NFS allow the configuration of read and write sizes. Normally an NFS version 2 client reads and writes files in 8k chunks, however some routers may drop UDP packets of this size and a smaller transfer size will yield better results. The Java NFS client provides no interface for setting transfer size. Transfer size is negotiated with the server.

How Do I Lock a File Using the Extended Filesystem API?

The Extended Filesystem API mirrors the file access functions available through the Java I/O package java.io. Neither package supports the ability to lock files. NFS clients generally lock files using the companion NLM (Network Lock Manager) protocol but this is not currently implemented in the Java NFS client. Where locking is not supported directly, applications can use a lock file as a substitute.

Where Can I Find Out More about NFS?

Version 2 and version 3 of the NFS protocol are described in RFC 1094 (version 2) (ftp://ftp.isi.edu/in-notes/rfc1094.txt) and RFC 1813 (version 3) (ftp://ftp.isi.edu/in-notes/rfc1813.txt). The WebNFS method of binding to the server is described in RFC 2054 (ftp://ftp.isi.edu/in-notes/rfc2054.txt) (client side) and RFC 2055 (ftp://ftp.isi.edu/in-notes/rfc2055.txt) (server side). The NFS URL scheme is specified in RFC 2224 (ftp://ftp.isi.edu/in-notes/rfc2224.txt). The X/Open Specification for NFS including descriptions of the MOUNT protocol and Network Lock Manager protocol can be ordered from The Open Group (http://www.opengroup.org/publications/catalog/c525.htm). If you are interested in comparing the performance of NFS servers from various vendors, take a look at the SPEC SFS Suite benchmark (http://www.specbench.org/osg/sfs). NFS vendors also test their client and server implementations for interoperability at Connectathon. For information on the administration of NFS on Solaris clients and servers, check the NFS Administration Guide. If you would like to communicate with other NFS users, administrators, or developers, try the Newsgroup comp.protocols.nfs.

How Do I Obtain the File Separator Character Using XFile?

The path separator for all URL schemes except "native" is a forward slash ("/"). If you are using native paths, the separator can be obtained via System properties. For example:

String s = System.getProperties().getProperty("file.separator")

Do I Have to Type a URL to Access Any Non-Native File?

There is some concern that URL naming could be awkward due to having to type the colons and multiple slashes typical of URL syntax. However, in an application context, as with Web browsers, users can operate within a naming context and use relative names. For instance, most URLs embedded in HTML documents use short, relative URLs. Similarly, when a user is selecting a file from a dialog window that contains the list of files in a directory, the "base" URL is the directory being displayed and the user can type, or click on, a relative name. Relative paths can also be used to name files in any subdirectory and the use of ".." components can be used to name files in parent directories. A full URL must be entered only to select a file on a different server or to name a file with a different URL scheme. For a description of relative naming using URLs see RFC 1808.

What Happens If a Relative Name Looks Like a URL?

An ambiguity could arise if a relative name looks like a URL. For instance, if the current directory of the Java Runtime contained a directory nfs: then a reference to a sub-directory nfs:/xxx/yyy might be intended, but the path would be evaluated as an NFS URL. If a filesystem that implements the URL scheme is currently loaded then the evaluation will fail and an error will be returned. To avoid this ambiguity the file must be identified by its absolute path,that is, the complete URL for the file. A short reference to the "native" scheme is . (period), so that a path beginning with .: is identified as a URL for a native path. If the apparent URL cannot be identified (no implementation available) then the name will be evaluated correctly within the directory indicated by the current URL context. Fortunately, file names with an appended colon are not popular. The only exception is the DOS disk letter naming, though most URL schemes use an identifier longer than a single letter -- so ambiguity is unlikely to be a problem.

How Do I Get or Set Attributes with XFile?

XFile supports access to the file attributes supported by java.io.File, for instance: canRead, canWrite, isFile, isDirectory, lastModified, and length; however, as yet there is no mechanism for obtaining filesystem-specific attributes, for instance, the UID of an NFS file. Access to these attributes will be provided in future releases within the XFile ExtensionAccessor classes.

How Do I Write an Accessor Class for a "Plug-in" Filesystem?

Refer to the WebNFS XFileAcessor Interface Reference which describes how to write an accessor class to support any filesystem scheme.

Why Isn't `XFile` a Subclass of `File`?

This would seem to make sense, particularly where a File object is used as an argument in the constructor for instances of FileInputStream() or RandomAccessFile(). Unfortunately, nearly all the methods in the File class interact directly with the JNI - it is not possible to interpose XFile as a filesystem-independent layer. In addition, classes that take a File in the constructor also work directly with the JNI. Eventually we expect XFile to be subsumed by an Extended Filesystem API in a future release of the Java JDK.