Documentation

Allegro NFS – Documentation

Allegro NFS Server supports NFS protocols V2 and V3. It has been tested against a large number of NFS clients, ranging from Linux, Solaris, macOS, FreeBSD, AIX, HP-UX and more.

Configuration overview

Exports

The primary configurable item in Allegro NFS Server is the export. Exports define a directory tree that will be made accessible to NFS clients. Exports have several important parameters:

User lists

A user list is a named list of numeric user ids. There is a built-in user list called “everyone” that implicitly includes any possible user id. There is also a built-in user list called “root” which includes user id 0. You can make your own user lists by selecting the “User lists” tab and clicking the “New” button. You will be prompted for the name of the new list. This will create an empty list. You can add user ids to the list by filling in the “New user id” edit box and clicking the “Add” button. You can add as many user ids as you want to a list. The same user id can be used in multiple lists. The simplest useful user list would have just one user id.

User list examples:

Let’s say you have the following remote users:

name:	  id:
joe	  150
bob	  160
jane	  170
sally	  180

You could make 4 new lists, each named after one of the users, and each of those lists could have one entry: the user id of the named user. Then you could add or remove any of those single-element user lists to any exports to give that user access.

If bob and jane are both software developers, you might make a list called “developers” and add user ids 160 and 170 to it.

Host lists

A host list is a named list of Internet Protocol (IP) host or network addresses. There is a built-in host list called “all” that implicitly includes any possible remote hosts. You can make your own host lists by selecting the “Host lists” tab and clicking the “New” button. You will be prompted for the name of the new list. This will create an empty list. You can add IP addresses to the list by filling in the “New address” edit box and clicking the “Add” button. You can add as many addresses as you want to a list. The same address can be used in multiple lists. The simplest useful host list would have just one address.

How to specify addresses:

Global settings

Logging settings

These settings allow the rotation of log files to be scheduled.  By default, no rotation is done and the log file being allowed to grow to an unlimited size.  If a non-zero Max log file size is set, then log files will be rotated when the log file reaches that size.  The number of log files to keep is set with Max # of log files and it defaults to 1.

Debug settings

Caching

Open file cache

Because the NFS protocol does not have an open call, clients simply make read and write calls to files. A basic implementation of a user-mode NFS server would have to open the file, do the read or write operation, then close the file for every block of data.

To avoid this potential constant opening and closing of the file, we employ an open file cache. The configuration program does not have an option to set this, but it can be set by editing the nfs.cfg file in the installation directory. If you edit the file, you will see this

(common-lisp-user::*open-file-reap-time* 2)

The default 2 seconds can be changed to any integer greater than zero.

The value of that parameter controls how long files are held open after their last access. The default value should be fine for most people but you may want to make an adjustment if your situation calls for it. Files will stay open for that number of seconds longer than the last access to it, and if a program on the server side tries to access the file, then it will fail due to Windows file locking.

When this parameter is zero, the server will not cache open files, but it will incur a performance penalty. That penalty might be better than sharing violations by the Windows operating system.

File attribute caching

Similarly, calls to stat() are cached for (default value: 5) seconds. Most NFS calls return information from the stat() call along with their results. Keep this in mind if you edit a file or directory locally on the NFS server. NFS clients may not see the change for up to this amount of seconds.

Note: the file attribute cache seconds should be larger than *open-file-reap-time* discussed above. This is because the open file reaper needs the cached stat information when closing a file that was opened for writing, so it can update the atime/mtime of the file.

Directory caching

When a client removes a directory containing files on the server, the way buffered reads of the directory entries is done can cause problems in NFSv2. It leads to a directory changing while the client reads it and it can lead to wildly inconsistent results and failure to remove the directory, because it is not empty.

This problem does not impact UNIX NFS servers because they were written with UNIX filesystems in mind, and also because they are implemented in the kernel. Allegro NFS is not implemented in the Windows kernel and it has to content with the Windows filesystems and operating system.

To make client directory removal work, we cache:

• information about directories. The Directory caching time (see above) defaults to 2 seconds. This cache contains the contents of the directory along with a time stamp, and
• client operations that modify a directory (unlink, create, rename) will be recorded in the directory cache, as long as they occur within the Directory caching seconds of the last operation.

This caching also has the side effect of making the operations a bit faster, but the important thing is that for removal of directories to work, the Directory cache time must be large enough for them to complete. Increase the value of this parameter if you are having problems.

Note: while a directory’s contents is cached, any changes to the directory made by a local user on the NFS server will not be visible to the NFS client for the number of cached seconds. Tuning may be needed to find a balance between directory removal success and confusion avoidance.

Misc

Exports should always grant at least read access to user id 0 (root) so that the root user on remote systems can successfully mount the export.

Umask/set-mode-bits: It may seem that the default file mode bits (typically rw-rw-rw-) that are reported by the NFS server are too loose. There is a reason for this, however. Most NFS clients will check the permission bits before sending requests to the NFS server. If the permission bits indicate that the operation would not succeed, the client does not send the nfs request to the server at all. This could be a problem when you are using complex user lists. Here is an example that will explain what can go wrong:

user list:
  testers: 400, 401, 402

export: 
  name: /testing
  path: c:\temp
  uid: 100
  gid: 100
  rw-user lists: testers
  umask: 0 (default)

With this setup, user ids 100, 400, 401, and 402 will have read/write access to export. The NFS client will see loose file permissions and will send all write requests over to the server. The NFS server will then do its own security checks and grant write access only to user ids 100, 400, 401, and 402. However, if the umask were set to 022 then the NFS client would conclude that the files could only be written to by user 100.. and attempts by user ids 400, 401, and 402 would not even be passed on to the NFS server, defeating the utility of user lists.

Using the default umask and set-mode-bits settings (both 0) will avoid this problem while still maintaining security.