These are the release notes for the NFS filesystem for Linux.

* Current Version

- NFS version 0.3a for Linux 0.98 patchlevel 6

* Status

- BETA, use with caution

* Limitations

- no read/write caching, minimal lookup/attribute caching, can't run binaries

* Copyright

- Rick Sladkey <jrs@world.std.com>

* Distrubution

- GNU copyleft as outlined in the GNU Public License version 2

* Where Available

- anonymous ftp from tsx-11.mit.edu:/pub/linux/ALPHA/NFS/nfs-client-0.3a.tar.Z

* References

- "NFS: Network File System Protocol specification," RFC 1094
- "RPC: Remote Procedure Call Protocol specification version 2," RFC 1057
- "XDR: External Data Representation standard," RFC 1014
- "User Datagram Protocol," RFC 768
- "Managing NFS and NIS," Hal Stern, O'Reilly, ISBN 0-937175-75-7

* How to Install

- please read this entire document before performing any installation
- ensure that TCP/IP is in your kernel and your network is set up and works
- unpack the main distribution somewhere
- unpack linux.tar in /usr/src, no existing kernel files will be overwritten
- patch the kernel from /usr/src using nfs.diffs, e.g. "patch -p0 <nfs.diffs"
- carefully note and manually install any failed patches or stop now
- run make dep in the kernel source directory
- rebuild the new kernel remembering to save your old one
- unpack mount.tar and shutdown.tar somewhere
- backup or save your old "mount", "umount" and "shutdown" commands
- install the new "mount", "umount" and "shutdown" commands
- recompile and install the "ps" suite of programs
- if your fstab mounts /proc then change the device from /dev/ram to none
- install and reboot the new kernel

* How to Use

- locate an NFS server and a directory that you can mount
- ensure that your server's sysadmin has exported the filesystem to you
- ensure that your uids and gids match those used by the server
- ensure that you have created the mount point for the directory
- issue the command "/etc/mount server-name:/server-dir /local-dir"
- cd into the new filesystem and test it
- optionally add one or more entries to your /etc/fstab with a type of "nfs"

* Special Notes

- modified mount command

I have included a modified mount command based on Doug Quale's
fstab-based mount package for Linux.  This section describes the new
mount command and why I had to modify it.

The mount program plays a crucial role in the NFS filesystem.  Unlike
many other filesystems, mount "knows about" NFS and performs actions
specific to the nfs type.  Things such as looking up the IP addresses
of hostnames or contacting portmappers and mount daemons are done by
the mount program on behalf of the kernel.  Then the mount program
passes a special data structure to the kernel through the mount system
call.

New options specific to the nfs type of filesystem:

option     (default)	meaning
-------------------------------------------------------------
noac       (off)	no attribute caching
rsize=n    (1024)	read buffer size
wsize=n    (1024)	write buffer size
hard       (on)		retry operations indefinitely
soft       (off)	return I/O error after a major timeout
timeo=n    (7)		timeout before retransmission in tenths of a second
retrans=n  (3)		number of minor timeouts before a major timeout
acregmin=n (3)		minimum seconds to cache attributes of regular files
acregmax=n (30)		maximum seconds to cache attributes of regular files
acdirmin=n (30)		minimum seconds to cache attributes of directories
acdirmax=n (60)		maximum seconds to cache attributes of directories
actimeo=n		sets all attribute caching timeouts at once
port=n     (2049)	which port to find the nfs service on

Other options which are parsed but not yet implemented:

option     (default)	meaning
-------------------------------------------------------------
nocto	   off		supress fresh attribute on file creation
posix	   off		request posix semantics on the mounted filesystem
intr	   off		allow signals to interrupt a pending transaction
bg	   off		retry the mount in the background
fg	   on		try the remote mount only in the foreground

For example to mount a filesystem with a read and write buffer sizes
of 2048, use "mount -o rsize=2048,wsize=2048 server:/server-dir /local-dir".

- modified umount command

I also modified Doug's umount command.  This sections describes why.

The traditional umount system call accepted the name of a block device
as its argument.  For "virtual" filesystems that are not assosicated
with true hardware block devices, it is awkward to provide a suitable
argument to umount.  For this reason, the mount system call now
accepts and understands mount points as well as block devices.  Since
all filesystems must have a distinct mount point by definition, this
interface is better suited for systems supporting virtual filesystems.
The umount command must use this new system call interface to properly
unmount virtual filesystems.

- modified shutdown command

I have included the shutdown command from Peter Orbaek's admutils-1.4
package.  It includes some changes I made for NFS.  If you already
have installed admutils-1.4, you don't need this version.

This version of shutdown (and reboot and halt) attempts to call
"umount -a" to unmount all filesystems and then, if that fails, it
tries to unmount them itself using the umount principles described
above.  In such a case it offers a few new features such as unmounting
filesystems in reverse order and not giving a message about failing to
unmount the root partition.

- backward compatibility of mount, umount and shutdown

I made some small concessions to purity to allow all the modified
commands to continue to work correctly with older kernels.  Therefore,
these versions are suitable for general use by older kernels, as well
as newer kernels with or without TCP/IP and NFS.

- /etc/rc and fstab considerations

If you include nfs mounts in your fstab, then you should change your
/etc/rc to run "mount -vat nonfs" instead of "mount -va" because your
networking will not have been configured yet and any NFS mounts will
fail at that point.  Then you can add "mount -vat nfs" to the end of
your rc.net file to mount any NFS filesystems after the network is up.

- increasing the maximum number of mounted filesystems

The standard Linux kernel allows 16 filesystems to be mounted.
With your ordinary filesystems and several NFS filesystems, you may
run up against this limit.  The limit of 16 is coded as
NR_SUPER in /usr/src/linux/include/linux/limits.h.  You may increase
this value as needed.

- retransmission timeout values

If you have a slow or busy server or your system is separated from your
server by a router or serveral bridges, you may get better performance
by increasing the default retransmission timeout value.  The value of
7 equations to 0.7 seconds.  You might try doubling it and see if it
improves performance.  See the Stern book for a detailed explanation
on how the timeout mechanism works.

- nomenclature

It may seem redundant to use the phrase "NFS filesystem" since NFS
stands for "Network File System" but the name actually refers to an
NFS client as opposed to an NFS server.  Thus, an unqualified
reference to NFS includes both aspects of the NFS protocol.  In this
context, "NFS filesystem" refers to the implementation of an NFS
client within an operating system or to the local directory structure
of a remote filesystem.

* General NFS Usage Guidelines

- read-only filesystems

Your mount of a server's filesystem should match the ro/rw option with
that of the server.  However, you may still mount it read-only even if
the server exports it read-write for extra safety during testing.  If
you mount it read-write and the server exports it as read-only you
will receive EROFS (Read-only filesystem) errors from the server when
attempting to write to the filesystem.

- mapping of root privileges

It is quite likely that your server will not allow root on your system
to be mapped into root on the server.  For this reason, you should
generally access NFS mounted filesystems using a uid that is valid on
that system.  Even so, root will be allowed to access world-readable or
world-writable files and directories.  Just be aware that being root
on an NFS client is sometimes the least privileged user you could
possibly be.

* Change Log

- Version 0.3 dated 92-11-09

Bug fixes:

Fixed a problem where current->timeout was not being reset to zero.

Fixed a minor memory leak in nfs_follow_link (reported and fixed
by Phil Packer <pep@wicked.demon.co.uk>).

New features:

NFS kernel diffs now incorporated into Linux kernel 0.98 patchlevel 4.
Shutdown diffs now incorporated into admutils-1.4.
Changed malloc functions to use new kmalloc interface.

- Version 0.2a dated 92-11-02

Bug fixes:

Fixed a "bug" where symlinks would crash SunOS (reported and fixed
by <jon@robots.ox.ac.uk>).

Fixed a minor memory leak and a fence-post bug in nfs_symlink.

- Version 0.2 dated 92-11-01

New features:

Timeout and retransmission are fully implemented (should fix any "hangs").
Preliminary lookup and attribute caching (better results with ls, pwd, etc.).
All mount options parsed and many implemented (rsize, timeo, etc.).

Bug fixes:

Now du reports block counts correctly (reported by Bob Green
<bob@inmos.co.uk>).

Fixed chmod on directories (reported by Ray Bellis <rpb@psy.oxford.ac.uk>).

Fixed hard links (reported by Ray Bellis <rpb@psy.oxford.ac.uk>).

Fixed mount points inside NFS filesystems (reported by Peter Chubb
<peterc@suite.sw.oz.au>).

- Version 0.1 dated 92-10-28

First released version.  No timeout or retransmission.  Only readir caching.