NFS2 Client

NFS2 Client

JNode's NFS (Network File System) v2 client implementation using ONC/RPC for remote filesystem access over IP networks.

Overview

JNode includes an NFSv2 client that allows mounting and accessing remote filesystem exports as if they were local block devices. The implementation follows RFC 1094 and uses the ONC/RPC (Open Network Computing Remote Procedure Call) protocol on top of UDP or TCP. The NFS client relies on the org.acplt.oncrpc library (part of the GNU Classpath auxiliary libraries) for RPC transport, XDR encoding/decoding, and portmap resolution.

The client is organized into two layers:

• NFS2 protocol layer (NFS2Client) — implements NFS procedure calls (LOOKUP, READ, WRITE, CREATE, etc.)
• Mount protocol layer (Mount1Client) — handles export listing and filesystem handle acquisition

The mount protocol is a separate ONC/RPC program (program 100005, version 1), while NFS is program 100003, version 2. A typical mount sequence is:

1. Use Mount1Client to resolve the export path to a file handle (32-byte opaque token)
2. Use NFS2Client with the file handle to perform directory listings, file reads/writes, attribute queries, etc.

Key Components

Class / File	Role
net/src/net/org/jnode/net/nfs/nfs2/NFS2Client.java	Main NFSv2 client implementing all NFS procedure calls (LOOKUP, READ, WRITE, CREATE, etc.) via ONC/RPC
net/src/net/org/jnode/net/nfs/nfs2/mount/Mount1Client.java	Mount protocol client (program 100005, v1) for export listing and mount requests
net/src/net/org/jnode/net/nfs/nfs2/NFS2Exception.java	Exception thrown on NFS procedure failures, wrapping ResultCode values
net/src/net/org/jnode/net/nfs/nfs2/ResultCode.java	Enum of NFS v2 status codes (NFS_OK, NFSERR_PERM, NFSERR_NOENT, etc.)
net/src/net/org/jnode/net/nfs/nfs2/FileAttribute.java	Container for NFS file attributes (type, mode, uid, gid, size, timestamps, etc.)
net/src/net/org/jnode/net/nfs/nfs2/FileSystemAttribute.java	Container for filesystem-level attributes (transfer size, block size, free blocks)
net/src/net/org/jnode/net/nfs/nfs2/mount/MountResult.java	Result from MOUNT procedure containing the 32-byte file handle
net/src/net/org/jnode/net/nfs/nfs2/mount/RemoteMountFileSystem.java	Simple holder of host + remote directory path
net/src/net/org/jnode/net/nfs/nfs2/mount/ExportEntry.java	Represents an exported filesystem with its path and client group list
net/src/net/org/jnode/net/nfs/nfs2/mount/MountException.java	Exception thrown on mount protocol failures
net/src/net/org/jnode/net/nfs/Protocol.java	Enum defining UDP or TCP transport selection

How It Works

RPC Client Management

Both NFS2Client and Mount1Client maintain a pool of OncRpcClient connections:

1. Portmap resolution — Before creating an RPC client, the portmap service (port 111) is queried to locate the target program (NFS program 100003 or MOUNT program 100005)
2. Connection pooling — A LinkedList<OncRpcClient> pool is maintained; getRpcClient() recycles or creates new clients
3. Authentication — Optional OncRpcClientAuthUnix authentication using UID/GID (passed as -1 to disable)
4. Timeout — Default 10-second timeout for all RPC calls
5. Retry logic — Up to 5 retries for transient OncRpcException failures; HTTP errors are propagated as NFS2Exception or MountException

File Handle

NFSv2 uses a fixed 32-byte opaque file handle (FILE_HANDLE_SIZE = 32) to identify files and directories on the server. The mount protocol returns the root file handle for a given export path; subsequent NFS calls use this handle as the parent reference.

NFS Procedure Calls

NFS2Client implements all major NFSv2 procedures via the call() method:

• LOOKUP (proc 4) — Resolve a filename within a directory to a file handle + attributes
• READ (proc 6) — Read up to MAX_DATA (8192) bytes from a file at a given offset
• WRITE (proc 8) — Write bytes to a file at a given offset
• CREATE (proc 9) — Create a regular file (mode ORed with 0x8000)
• CREATE_DIR (proc 14) — Create a directory (mode ORed with 0x4000)
• REMOVE (proc 10) — Delete a regular file
• REMOVE_DIR (proc 15) — Delete an empty directory
• RENAME (proc 11) — Rename a file or directory
• GETATTR (proc 1) — Query file attributes
• SETATTR (proc 2) — Set file attributes
• READ_DIR (proc 16) — List directory entries with cookie-based pagination
• FSSTAT (proc 17) — Query filesystem statistics

XDR Encoding/Decoding

NFS and Mount protocol data use XDR (External Data Representation) for serialization. Both clients use anonymous inner classes implementing XdrAble for parameter encoding (xdrEncode()) and result decoding (xdrDecode()):

• Parameters — Anonymous NFSParameter / Parameter subclasses with XDR encoding for request payloads
• Results — Anonymous NFSResult / Result subclasses that decode server responses into result objects
• Status handling — A ResultWithCode wrapper checks the status code before decoding the result body; non-NFS_OK codes throw NFS2Exception

Mount Operations

Mount1Client provides:

• MOUNT (proc 1) — Returns file handle for an export path
• EXPORT (proc 5) — Lists all exported filesystems from the server
• DUMP (proc 2) — Lists currently mounted filesystems
• UNMOUNT (proc 3) — Releases a mount

Gotchas

• NFS2 only — This is an NFSv2 (protocol version 2) client. NFSv3/v4 are not implemented.
• Stateless design — NFS is stateless; the client must track file handles and position independently. JNode's NFS2Client does not provide a filesystem abstraction; it is a low-level RPC client.
• No VFS integration — There is no FileSystemType or FileSystem implementation for NFS in JNode. To fully integrate NFS into the VFS, a higher-level layer would need to be added.
• 8KB max transfer — NFS READ and WRITE are limited to MAX_DATA = 8192 bytes per call; larger transfers require chunking.
• Limited retry — Retry logic only handles OncRpcException; other I/O errors propagate immediately.
• Hardcoded constants — FILE_HANDLE_SIZE = 32, MAX_DATA = 8192, MAX_NAME_LENGTH = 255, MAX_PATH_LENGTH = 1024 are hardcoded and not negotiated.
• XDR unsigned int — xdrDecodeUnsignedInt() manually sign-extends a 4-byte opaque buffer (no direct unsigned API).

Related Pages

• Network-Stack — Network protocols and the stack architecture
• Network-Layers — Protocol layering (LinkLayer, NetworkLayer, TransportLayer)
• VFS-Layer — In-memory virtual filesystem and mount mechanism
• Filesystem-Layer — Block device and filesystem drivers