unfsd(8)

NAME
unfsd - NFS server process

SYNOPSIS
/usr/sbin/unfsd [options]

DESCRIPTION
The unfsd program implements the MOUNT and NFS version 3 protocols. It listens for client requests, performs them on the local filesystem of the server, and then returns the results of the operations to the clients.

At startup, unfsd reads the exports file, /usr/pkg/etc/exports by default, to find out which directories are available to clients and what options are in effect (see EXPORTS FILE section below for syntax and possible options).

Normally, unfsd should be run as the root user. It will then switch its effective user and group id to the numbers listed in incoming NFS requests. This means filesystem operations will be performed as if done by a local user with the same ids. If the incoming request is for user or group id 0 (meaning root), unfsd will switch to the user and group id of the nobody user before performing filesystem operations (this is known as root squashing). If the user nobody does not exist on the system, a user and group id of 65534 will be used. This behavior can be modified by use of the no_root_squash and all_squash options in the exports file as well as the anonuid and anongid options on a per-share basis.

If unfsd is running as a normal unprivileged user, no switching of the effective user and group id will take place. Instead, all filesystem operations will be performed with the id of the user running unfsd.

RESTRICTIONS
Some NFS clients may attempt to perform operations that unfsd cannot fully support.

Object Creation
    When creating filesystem objects, it is only possible to specify the initial mode for the object. The initial user and group ownership, object size, and timestamps cannot be specified and will be set to default values.

File Locking
    The network lock manager (NLM) protocol is not supported. This means that clients may have to mount with special mount options, disabling locking on the mounted NFS volume (nolock for Linux clients).

OPTIONS

-h  Display a short option summary.

-e <file>
    Use the given file as the exports file, instead of using /usr/pkg/etc/exports. Note that the file needs to be specified using an absolute path.

-i <file>
    Use the given file as pid file. When the daemon starts up, it will write its pid (process id) to the given file. Upon exit, the daemon will remove the file. Failure to create or remove the pid file is not considered fatal and only reported to syslog.

-u  Use an unprivileged port for NFS and MOUNT service. Normally, unfsd will use port number 2049, which is the standard port for NFS. When this option is in effect, arbitrary ports chosen by the RPC library will be used. You may need to use this option when running unfsd from a normal user account.

-n <port>
    Use the specified port for the NFS service.

-m <port>
    Use the specified port for the MOUNT service. The default is to use port number 2049, the same as for the NFS service. You can use the same port for both services if you want.

-t  TCP only operation. By default, unfsd provides its services to clients using either UDP or TCP as communications protocol. When this option is present, only TCP connections are serviced.

-p  Do not register with the portmapper. This will prevent other hosts from finding out the port numbers used for the MOUNT and NFS services by querying the portmap daemon. Clients will need to manually specify the port numbers to use (on Linux clients, use the mountport and port mount options).

-c  Enable cluster extensions. This feature is only available when unfsd was compiled with cluster support. When this option is enabled, so-called tagged files are handled differently from normal files, making it possible to serve different file contents to different clients for the same filename. See tags(7) for a description of tagged files. This option causes a performance hit.

-C <path>
    Limit the use of cluster extensions to a list of colon-seperated directories. When this option is present, the performance hit caused by clustering extensions only applies to the listed directories and their subdirectories.

-s  Single user mode; activate basic uid translation. This option is useful when the server and client are using different user and group ids. All requests from the client will be served from the user id that started unfsd, no user id switching will take place (even if unfsd was started by root). Ownership is reported as follows: files belonging to the user id running unfsd will look as if they are owned by the client's user. Other files will look as if they are owned by root. The same principle applies to group ownership.

-b  Enable brute force file searching. Normally, when you rename a file across several directories on an NFS volume, the filehandle for that file becomes stale. When this option is enabled, unfsd will attempt a recursive search on the relevant server filesystem to find the file referenced by the filehandle. This can have a huge performance impact as this will also happen for files that were really deleted (by another NFS client) instead of moved, and cannot be found.

-l <addr>
    Bind to interface with specified address. The default is to bind to all local interfaces.

-d  Debug mode. When this option is present, unfsd will not fork into the background at startup, and all messages that would normally go to the system log go to stdout instead.

-r  Report unreadable executables as readable. This applies both to returned attributes and ACCESS requests. Please note that READ requests for unreadable executables are always allowed, if unfsd is running as root, regardless of this option.

-T  Test exports file and exit. When this option is given, unfsd will try to parse the exports file and exit with status 0 if this is successful. If there is a syntax error in the exports file, a message is printed on standard error and unfsd exits with status 1.

SIGNALS

SIGTERM and SIGINT
    will cause unfsd to unregister itself from the portmapper and exit.

SIGHUP
    will cause unfsd to re-read its configuration data. Currently, this means the program will query the passwd database to find out the user and group id of user nobody. unfsd will also attempt to reload the exports file. If the exports file contains errors, unfsd sends a warning message to the system log and nothing is exported until the situation is corrected and another SIGHUP is sent.

SIGUSR1
    will cause unfsd to output statistics about its filehandle and file descriptor cache to the system log. For the filehandle cache, it will output the number of filehandles in the cache, the total number of cache accesses, and the number of hits and misses. For the file descriptor cache, it will output the number of currently held open READ and WRITE file descriptors.

EXPORTS FILE
The exports file, /usr/pkg/etc/exports by default, determines which directories on the server can be accessed from NFS clients. An example:
# sample NFS exports file
/home            trusted(rw,no_root_squash) (ro)
"/with spaces"   weirdo
/usr             1.2.3.4(rw) 192.168.2.0/24(ro,all_squash)
/home/foo        bar(rw) 10.0.0.0/255.0.0.0(root_squash)
/home/joe        joes_pc(anonuid=1100,anongid=1100,rw,all_squash)
Comments start with a # character and cause the rest of the line to be ignored. Extremely long exports can be split across multiple lines by escaping the intermediate newlines with a backslash character.

Each line starts with a directory that is to be exported. If the directory name contains whitespace, it must be enclosed in double quotes. To the right of the directory name, a list of client specifications can be given. If this list is missing, the directory is exported to everyone, using default options (ro and root_squash).

If the directory name contains symbolic links, they are expanded. This means that you have to force unfsd to reload the exports file if the symlinks happen to change.

Clients can be specified using either a hostname, an IP address, or an IP network. Networks can be given by specifying the number of leading 1 bits in the netmask or by giving the full netmask. If the hostname is empty, the directory is exported to everyone.

Options can follow a client specification and have to be enclosed in parenthesis, with the opening paren directly following the client name or address. If no options are given, ro and root_squash are enabled by default. The following options are supported by unfsd:

root_squash
    Enable root squashing, mapping all NFS request done with a user id of 0 to the user id of the nobody user. This option is enabled by default.

no_root_squash
    Disable root squashing. When this option is present, NFS requests done with a user id of 0 will be done as the root user of the server, effectively disabling all permissions checks.

all_squash
    Squash all users. When this option is present, all NFS requests will be done as the nobody user of the server.

no_all_squash
    Don't squash all users. This option is enabled by default.

rw  Allow read and write access on the exported directory. When this option is present, clients are allowed to modify files and directories on the server.

ro  Allow only read access on the exported directory. When this option is present, clients are not allowed to modify files and directories on the server. This option is enabled by default.

anonuid/anongid
    Sets the uid and gid for anonymous mounts for this share - by default the uid for nobody will be used, but using these options you can change this on a per-share basis.

secure
    Allow only mount requests coming from a source port below 1024. Using these ports requires super-user privileges on many operating systems. This option is enabled by default.

insecure
    Allow mount requests coming from any source port.

removable
    Consider this directory to be on a removable medium. When this option is present, unfsd will not keep files open across multiple read or write requests. This allows unmounting of the underlying filesystem on the server at any time. Also, unfsd will not require that the exported path exists at startup or mount time. If the path does not exist, an empty directory will be presented to the client. This is useful for exporting mount points handled by autofs.

fixed
    Consider this directory to be on a fixed medium. This options is enabled by default and allows unfsd to keep files open between multiple read or write requests.

password=<password>
    To be able to mount this export, the specified password is required. The password needs be given in the mount request, as in "mount yourhost:@password:gazonk/tmp /mnt". One time passwords are also supported. When using passwords, the file handles will include a hash of the password. This means that if you change the password, all clients will need to remount this export. See the file "doc/passwords.txt" in the source for more information.

If options not present on this list are encountered by unfsd, they are silently ignored.

BUGS
There are a few possible race conditions with other processes on the server. They can happen if unfsd is performing an operation on a filesystem object while another process is simultaneously first (a) removing the object and then (b) creating a new object of the same name. If this happens, unfsd will attempt to perform the operation on the wrong, new object. The time window in which this can happen is small.

When a client does a CREATE EXCLUSIVE procedure call, unfsd stores the verifier data in the mtime and atime attributes of the created file. Malicious processes on the server could manipulate those attributes, breaking the semantics of the exclusive create operation. A process attempting to do so would need to be able to see the NFS network traffic.

unfsd always uses the "nohide" semantics, which means that clients will see all file systems mounted below the exported path. However, some NFS clients do not cope well with this situation as, for instance, it is then possible for two files in the one apparent filesystem to have the same inode number. To avoid this, make sure that the client mounts each exported file system.

Due to the way unfsd operates, it needs execute (lookup) and read permission on all directories from the root directory all the way up to exported directories. For example, if /usr/share is exported, unfsd is going to need permission for /, /usr, and /usr/share. Since root squashing can be in effect, unfsd may run as the nobody user, which normally means having to grant execute (lookup) and read permission for everybody on the server. In the above example, unfsd also needs permission to access /usr/share/.., which can be different from /usr for some special setups (for example when using bind mounts under Linux).

FILES

/usr/pkg/etc/exports
    Default exports file.

AUTHOR
Pascal Schmidt

SEE ALSO
tags(7)