Java Network File System README

Michael John Radwin

Extended Abstract

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


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.


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.


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:


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 package. The table below presents an overview of the file classes in the package and their JNFS equivalents. Each of these JNFS client classes inherits from either its counterpart or from an ancestor of its counterpart.
Table: file classes and their JNFS equivalents.
package  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 


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:

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 \
      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

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.


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

 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.


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:



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:


Running the server on

Here are more specific instructions for launching the server on
cd /home/mjr/src
unset noclobber
setenv CLASSPATH /home/mjr/src
ls -laR / > /tmp/ls-laR
java jnfs.FileServerStarter /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

Here's a series of commands that will create a trust relationship with the jnfs demo that work on
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)]


Source code, classfiles, and certificate

API Documentation (generated with javadoc)

Michael J. Radwin

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