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:

name	The name of an export is the string that clients use to identify the export. While just about any string is allowed, it is recommended that you use a string that doesn’t contain any spaces or other characters that have special meaning in a Unix shell. Also, export names customarily begin with a slash (/), but this is not a requirement. Export names exist in a hierarchical namespace. When an NFS client requests a mount for an export, the deepest matching export is used. For example, consider the following set of exports: /my-exports /my-exports/top-level/sub1 /my-exports/top-level/sub2 A mount request for /my-exports/top-level will use the /my-exports export. Also note that a mount request for my-exports, /my-exports, or /my-exports/ will all use the /my-exports export.
path	This is the local directory that will be shared by the export. It can also be a UNC share (e.g., \\host\share).
uid	All files will appear to be owned by this user id. NFS Clients accessing with this user id will have read/write permission to all files in the export.
gid	All files will appear to be owned by this group id. In Allegro NFS Server, the group id does not play any part in controlling access permissions.
umask	This alters the file mode bits that are reported to NFS clients. By default, all regular files report mode `0666` (`rw-rw-rw-`) mode. Files with filename extensions that are usually executable (.exe, .com, .bat, etc) report mode `0777` (`rwxrwxrwx`). Directories report mode `0777`. You can use the umask to turn some of the default mode bits off before reporting them back to the client. Unless you have special needs, it is recommended that you leave the umask setting at `0`. The parameter is expressed in octal notation.
set mode bits	This parameter is the inverse of the umask. It is expressed in octal notation and specifies which mode bits should be turned on before reporting them back to the client.
allow host lists	By default, no remote hosts are allowed to access an export. You can use this parameter to specify lists of remote hosts/networks that should be granted access. See below for more information on host lists.
read/write user lists	Remote users having user id matching the “uid” parameter (above) automatically have read/write access. You can use the read/write user lists parameter to specify lists of other users that should also have read/write access. You can select more than one list. See below for information on user lists.
read-only user lists	Remote users having user id matching the “uid” parameter (above) automatically have read access. You can use the read-only user lists parameter to specify lists of other users that should also have read-only access. You can select more than one list. See below for information on user lists.

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:

IP address	This is just the IP address of a host, in dotted (`xxx.xxx.xxx.xxx`) notation. This is used for specifying single hosts.
CIDR format	You can specify a range of addresses this way. The format is `xxx.xxx.xxx.xxx/pp`, where `xxx.xxx.xxx.xxx` is the network address and `pp` specifies the prefix length, that is, the number of bits that form the network part of the address. For example, `1.2.3.0/24` matches any address of the form `1.2.3.xxx`.
IP address/netmask format	You can specify a range of addresses this way as well. The format is `xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy` where `xxx.xxx.xxx.xxx` is the network address and `yyy.yyy.yyy.yyy` is the netmask. For example, `3.4.5.0/255.255.255.0` matches any address of the form `3.4.5.xxx`.

Global settings

Use system portmapper	Possible values are auto (the default), yes and no, meaning auto-detect and use another running portmapper, always use the system portmapper and always use the Allegro portmapper, respectively. auto is the best choice for most installations. If you choose yes and no portmapper is running on your system, then Allegro NFS will not be able to start up properly. Likewise, if you choose no and a portmapper is running on your system, then Allegro NFS will not be able to start up properly. A manual restart of the NFS service or a system reboot is needed if this parameter is changed.
Set file modification time after every write	This sets the file modification time on each write and is approximately slows down writes by 10%. The default is unchecked.
Subprogram port assignment	If you want to assign port numbers to the nfs subprocesses (mountd, statd, and lockd) so that they always use a specific port, you do so here. If you have a firewall, we recommend that you read this FAQ entry for more information on this topic.
Disable export listings via remote `showmount`	If this option is checked, then clients using the `showmount` command cannot obtain a listing of all exports. This might be desired for security reasons.
Disable persistent file handles	For NTFS volumes, by default, the server keeps a mapping from client file handles to local file names. This means when the server is restarted (the NFS service or the machine), clients will not got a stale file handle error. There is overhead to maintain this mapping, and when a large number of files are involved, it could be significant. Checking this option turns off this feature. The default is unchecked.
Directory caching time	The amount of time directory contents are cached. See the Caching section below for more information. The default for this value is 2 seconds.
File attribute caching time	The amount of time file attributes (`size`, `mtime` and `ctime`) are cached. See the Caching section below for more information. The default for this value is 5 seconds.
Truncate file-ids to 32-bits for clients	This option should only be turned on for badly behaved clients that cannot handle 64-bit file-ids (it is a bug in the client). When turned on, file-ids are truncated to 32-bits to make those buggy clients happy. The default is unchecked.

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

NFS, et al protocol debugging	You can turn these options on if you want to see what’s going on at the protocol level. Debugging output will be generated in the console window and in the current log file (see the configuration utility to determine the name of the current log file). Be careful! Turning on NFS protocol debugging can generate lots of output and severely degrade the performance of Allegro NFS. It can also lead to filling up your installation disk. When checked, the NFS protocol debugging item allows selection of individual NFS procedures to be logged. By default all procedures are logged.
Memory management debugging	This option prints detailed information about memory management. It should probably only be turned on at the request of the support department.
Log time stamps	This option causes each log entry to be given a date and time stamp, so behavior of server and clients can be correlated.

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.