Java Network File System README

Michael John Radwin

michael@radwin.org

Extended Abstract

This section of the README is a condensed version of the article "A Java Network File System for Network Computers."

Adobe Acrobat PDF (175K)
HTML (converted by LaTeX2HTML)

Introduction

We introduce and discuss the Java Network File System (JNFS), a network file system for Network Computers (NCs). JNFS works on all NC-compliant NC devices, provides authentication and authorization support, works with other file systems such as NFS and NTFS, and offers reasonable performance.

Background

Network Computer Reference Profile

The Network Computer Reference Profile (NCRP) is a set of guidelines offered by Apple, IBM, Netscape, Oracle and Sun as a ``common denominator of popular and widely used features and functions''. It defines minimum hardware requirements and software protocols necessary to achieve NC-compliance. Among the required protocols and software are TCP/IP and the Java Application Environment.

The NCRP specification proposes that Sun's Network File System (NFS) be optionally used as a file system for NC devices: ``NCs which do not implement a distributed file system need not implement this protocol''. It does, however, mandate support of the TCP/IP-based Hypertext Transfer Protocol (HTTP) to enable Web browsing and the File Transfer Protocol (FTP) for file exchange.

NFS Support on Low End NCs

Many of today's low-end NCs come with no NFS support or only provide it as an option. HDS Network Systems, for example, makes a family of NC-compliant devices called the @workStation. In its most basic configuration, the @workStation has no file system support, although it does have a full Java implementation. More expensive @workStation configurations include full NFS support. Boundless Technology's Network Computer XL and XLC are configured similarly; Java support comes on all computers and NFS is optional.

Motivation

Since the NCRP does not require a file system and lower-end NCs do not provide one, JNFS fills this need. In addition, since JNFS provides a network file system interface to a host's native file system, all NCs can access file systems other than NFS.

Design Goals

We had several goals in mind when we designed JNFS. First and foremost, the file system client had to run on all network computers. Since a number of vendors are shipping several different types of NCs, it would be ideal to develop a single client that works on all of them. Second, the file system had to provide some form of authentication and access control to ensure that unauthorized users could not gain access to files. In addition, the file server had to be interoperable with other types of file systems, and performance had to be reasonably good. Our implementation of JNFS achieved many of these goals:

Because the NCRP mandates support of the Java Application Environment, a Java implementation of JNFS ensures that it will work on all NC-compliant devices.
Good security is provided by both an authentication protocol based on digital signatures, and an Access Control List implementation for granting access to files.
Interoperability with other file systems is provided because JNFS runs on top of a native file system. Thus, JNFS can provide access to files served over both local file systems such as NTFS or a UNIX local file system, as well as network file systems such as NFS or DFS.
Performance is slower than NFS, but reasonable for a Java application. On average, JNFS file transfers take about 8 times as long as analogous NFS transfers.

Architecture

Figure: An overview of the JNFS architecture. Both the client and server are implemented in Java and communicate using RMI. The client runs on any NC or PC with the Java Application Environment; the server runs as a user-level daemon over a native file system and operating system.

Both the JNFS client and server were developed with Sun's Java Development Kit 1.1. The client will run on both any NC-compliant device as well as PCs with the Java support. The server is also written Java for ease of portability. An overview of the architecture is presented in the above figure.

The JNFS server runs as a user-level daemon as the privileged user (for example, root on UNIX, or any user with the Administrative Privilege on Windows NT). It serves out files from the underlying file system(s) used by the host operating system. Thus, if the server's operating system provides support for distributed file systems such as NFS, JNFS will serve those files out as well.

Remote File Classes

At the core of JNFS is a client-side class library that mirrors the functionality of the standard Java file classes in the java.io package. The table below presents an overview of the file classes in the java.io package and their JNFS equivalents. Each of these JNFS client classes inherits from either its


java.io

counterpart or from an ancestor of its


java.io

counterpart.

**Table:** `java.io` file classes and their JNFS equivalents.
package `java.io`	package `jnfs`	purpose
File	RemoteFile	pathname abstraction, file attributes
FileInputStream	RemoteFileInputStream	read-only input stream
FileOutputStream	RemoteFileOutputStream	write-only output stream
RandomAccessFile	RemoteRandomAccessFile	read/write, block-oriented random access
FileReader	RemoteFileReader	character file input
FileWriter	RemoteFileWriter	character file output
	FileServer	gives back filehandles, provides user info

Performance

Figure: Read performance of the JNFS system vs. NFS on several different file sizes.

Performance in our simulations was reasonable for a Java application, but not nearly as good as NFS. On average, JNFS file transfers take about 8 times as long as analogous NFS transfers on a Sun SparcStation 10 running Solaris 2.5. We present a comparison of JNFS and NFS read speeds on various different file sizes in the above figure. There are several factors that lead to worse performance in our simulation:

The JNFS server runs as a user-level daemon over a native file system. Since it does not run as part of the kernel, it incurs a large expense in traps to the kernel. Similarly, the client also runs in user space, which further worsens performance.
Since the Java byte-codes are interpreted instead of executed natively, actual execution of the file system code is much slower. On an NC, NFS would be slower because it would be implemented in Java instead of a compiled language.
The RMI networking protocol has a large overhead in comparison with NFS's UDP-based implementation. Although many of the JNFS functions transfer a block of data across the network, the RMI service still marshals and un-marshals this data, resulting in more copying than necessary.

Accompanying Files

You should find the following files in this directory:

Filename	Description
`public_html/jquest-README.html`	This document, in HTML format.
`public_html/demo.html`	The demo applet which must be run with appletviewer (see "Running the demo")
`public_html/jnfs.jar`	A signed jarfile of the server and client code, as well as the demo applet.
`public_html/jnfs.x509`	The X509 certificate for the jnfs entity.
`public_html/signer.guest`	Serialized private key file for the guest user.
`public_html/usertab.obj`	The user table of public keys. Contains entries for foo, mjr, tag, guest, bar, and admin.
`src`	The root of the directory tree containing the JNFS source code and class files.
`src/users/signer.*`	Serialized private key files for individual users.
`src/users/identity.*`	Serialized public key files for individual users.

Running the server

The server is a user level application which requires some command line parameters, explained below. After setting the


CLASSPATH

appropriately to include the src directory (or to the full path of jnfs.jar), start the server by issuing the following command:

 java jnfs.FileServerStarter fully.qualified.host.name \
      dirListingPathname groupPathname passwdPathname

Please forgive the lengthy explanation of the command-line parameters. Much care was taken to make sure that the server is platform-independent, so it is crucial to understand the structure of the configuration files so they can be generated if the server is not a UNIX machine. As a matter of convenience, these configuration files mimic the structure of standard files found on a UNIX machine.

Explanation of command line parameters

`fully.qualified.host.name`

In order to fix a design flaw in the Java RMI registry, the fully qualified domain name of the server must be provided. On UNIX, the hostname command should supply the name of the machine.

`dirListingPathname`

The directory listing is file formatted like the output of the UNIX ls -laR command. This file tells the server what permissions to associate with each file. An example is given below, where the first column lists the permission bits, the third lists the owner, the fourth lists the group, and the ninth the filename. All other fields are required but ignored.

The filename separator used to indicate which directory the files belong to must conform to the system-dependent file separator string (for example, "/" on unix and "\" on WinNT). A fragment from a directory listing is given below:

 /:
 total 129
 drwxr-xr-x  32 root     root        1024 Feb 25 13:05 .
 drwxr-xr-x  32 root     root        1024 Feb 25 13:05 ..
 dr-xr-xr-x   2 root     root           3 May 21 15:40 bin
 lrwxrwxrwx   1 root     root           9 Jan  6 19:47 lib -> ./usr/lib
 drwx------   2 root     root        8192 Jan  6 19:47 lost+found
 drwxrwxr-x  25 root     sys         1024 Jan  7 09:16 usr

 /bin:
 total 18944
 drwxrwxr-x   2 root     bin         7168 Mar 18 05:13 .
 drwxrwxr-x  25 root     sys         1024 Jan  7 09:16 ..
 -r-sr-xr-x   1 root     bin        32868 Jan 29 05:13 login
 -r-xr-xr-x   1 bin      bin        17500 Oct 25  1995 ls
 -r-x--s--x   1 bin      mail       66208 Jan  6 20:16 mail

If you're running JNFS on Win32, you'll need a program that can do the equivalent of the UNIX command "/bin/ls -laR". I'd recommend installing the GNU-Win32 toolkit. After running their "ls -laR", you'll need to open up the file in an editor and search/replace all /'s with \'s.

`groupPathname`

The group file must be formatted like a UNIX


/etc/group

file. This file tells the server the membership of each group. If the server is being run on a UNIX system, passing /etc/group as this parameter will work fine.

If one needs to generate a group file (if the server runs Windows NT or MacOS), the following format may be used. The file must consist of a one-line entry for each group recognized by the system, of the form:

groupname:password:gid:user-list

where

groupname is the name of the group.
gid is the group's unique numerical ID within the system.
password is ignored. May be left blank.
user-list is a comma-separated list of users allowed in the group.

`passwdPathname`

The password file must be formatted like a UNIX /etc/passwd file. This file tells the server the principal group id associated with each user. If the server is being run on a UNIX system, passing


/etc/passwd

as this parameter will work fine.

If one needs to generate a password file (if the server runs Windows NT or MacOS), the following format may be used. The file must consist of a one-line entry for each user of the form:

username:password:uid:gid:gcos-field:home-dir:login-shell

where

username is the user's login name.
gid is the user's numerical group ID.
All other entries are required but ignored. The password field may be left blank, but all other fields may not be blank.

Running the server on `jquest.acm.org`

Here are more specific instructions for launching the server on jquest.acm.org:

cd /home/mjr/src
unset noclobber
setenv CLASSPATH /home/mjr/src
ls -laR / > /tmp/ls-laR
java jnfs.FileServerStarter jquest.acm.org /tmp/ls-laR /etc/group /etc/passwd

Running the demo client

The demo applet shows off very little of the power of the file server and exercises only a small portion of the code. It is provided only to demonstrate that the server is indeed working and performing authentication and authorization correctly.

The demo is an applet, but requires special access privileges that Java does not normally grant applets (it calls System.runFinalizersOnExit(true), which for some silly reason is considered dangerous). Thus, it must be a "trusted" applet to run in the HotJava 1.0 browser or the JDK1.1 appletviewer.

You'll need to obtain the jnfs x509 certificate and then use the javakey tool to trust the jnfs entity. Once you've got the certificate, run:

javakey -c jnfs true
javakey -ic jnfs jnfs.x509
javakey -ld

Running the client on `jquest.acm.org`

Here's a series of commands that will create a trust relationship with the jnfs demo that work on


jquest.acm.org

javakey -c jnfs true
javakey -ic jnfs /home/mjr/public_html/jnfs.x509
javakey -ld

Once you've trusted the jnfs entity (you'll notice a file called identitydb.obj in your home directory), you can launch the demo via:

appletviewer demo.html

Manipulating the user database (`usertab.obj`)

As described in the paper, the JNFS performs authentication using a challenge-response protocol based on digital signatures. In order to maintain a user database, we provide a user management tool which modifies the user database. While the server is running, user management may be done by the admin user remotely. User information is stored in the file usertab.obj.

The usage and description of options follows:

 java jnfs.UserTool [-r host] {add | new | del | list}
                    [user(s) | identity_file(s)]

The -r option uses the UserManager interface on host instead of locally on usertab.obj.
The new and del options both take a a list of usernames. The del option removes each user specified; the new option creates FileSystemUsers and FileSystemSigners for each username specified.
When using the new option, the UserTool creates a public key file called identity.username and a private key file called signer.username. After generating identity.username, the add option may be used to update the user database.
The add argument takes a list of files. Each file should consist of a serialized a FileSystemUser.
The list option takes no other arguments.

Appendix

Source code, classfiles, and certificate

Download source tree, test suites, and demo:
- jnfs_src.tar.gz (49K)
jnfs.jar -- signed java archive of classfiles.
jnfs.x509 -- X509 certificate for jnfs entity.

API Documentation (generated with javadoc)

Browse documentation online
Download compressed documentation:
- jnfs_api.tar.gz (53K)

Michael J. Radwin

Last modified: Mon Nov 4 19:12:18 EST 2002