unfsd(8)

📦
version 0.10.0 · 2 versions
, in alpine 3.22, alpine 3.23, alpine 3.24

💅 unfsd(8) — NFS server process 💅

okay so bestie, welcome to unfsd, aka the NFS server process, and honestly this one is kind of a big deal 👑. It lives at /usr/sbin/unfsd and it's the whole reason your clients can reach into your filesystem and grab stuff. Let's get into it ✨

🌸 SYNOPSIS 🌸

/usr/sbin/unfsd [options]

💖 DESCRIPTION 💖

So like, the unfsd program implements the MOUNT and NFS version 3 protocols. It sits there listening for client requests, does the actual work on the server's local filesystem, and then hands the results right back to the clients. main character energy fr fr 💅

At startup, unfsd reads the exports file — /etc/exports by default — to figure out which directories are available to clients and which options are in effect (peep the EXPORTS FILE section below for the syntax and the possible options 👀).

Normally, unfsd should be run as the root user. When it is, it switches its effective user and group id to the numbers listed in incoming NFS requests. That means filesystem operations get performed as if they were done by a local user with the same ids — cute, right? 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 doing any filesystem operations (this is what we call root squashing 🙈). If the nobody user doesn't exist on the system, a user and group id of 65534 gets used instead. You can tweak this behavior with the no_root_squash and all_squash options in the exports file, plus the anonuid and anongid options on a per-share basis ✨

If unfsd is running as a normal unprivileged user, there's no switching of the effective user and group id at all. Instead, every filesystem operation is performed with the id of the user running unfsd. no cap 🫶

🦋 RESTRICTIONS 🦋

Some NFS clients may attempt operations that unfsd simply cannot fully support. Not her fault, she's doing her best 💀

🎀 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 just be set to default values. yeah. that's the deal 🍓

🎀 File Locking

The network lock manager (NLM) protocol is not supported. Which means clients may have to mount with special mount options, disabling locking on the mounted NFS volume (nolock for Linux clients). lowkey important, don't skip this one 😭

✨ OPTIONS ✨

  • -h — Display a short option summary. the little snack version of the manual 💖
  • -e <file> — Use the given file as the exports file, instead of using /etc/exports. Note that the file needs to be specified using an absolute path — no shortcuts bestie, absolute or nothing 💅
  • -i <file> — Use the given file as pid file. When the daemon starts up, it writes its pid (process id) to the given file. Upon exit, the daemon removes the file. Failure to create or remove the pid file is not considered fatal and is only reported to syslog. so like, she tries, but it's not that deep 🫶
  • -u — Use an unprivileged port for NFS and MOUNT service. Normally unfsd uses 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 this one 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, same as for the NFS service. You can use the same port for both services if you want — sharing is caring 💜
  • -t — TCP only operation. By default, unfsd serves clients using either UDP or TCP as the communications protocol. When this option is present, only TCP connections are serviced.
  • -p — Do not register with portmap/rpcbind. This prevents other hosts from finding out the port numbers used for the MOUNT and NFS services by querying the portmap or rpcbind daemon. Clients will need to manually specify the port numbers to use (on Linux clients, use the mountport and port mount options). stealth mode activated 🙈
  • -c — Enable cluster extensions. This feature is only available when unfsd was compiled with cluster support. When 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. Heads up though: this option causes a performance hit 💀
  • -C <path> — Limit the use of cluster extensions to a list of colon-separated directories. When this option is present, the performance hit caused by clustering extensions only applies to the listed directories and their subdirectories. smart girl behavior, limiting the damage 🎀
  • -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, and 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're owned by the client's user. Other files will look as if they're 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. Big warning though: this can have a huge performance impact, because it will also happen for files that were really deleted (by another NFS client) instead of moved — and those can't 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. front-row seat to the drama 🍓
  • -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. iykyk 👀
  • -T — Test exports file and exit. When this option is given, unfsd tries to parse the exports file and exits with status 0 if that's successful. If there's a syntax error in the exports file, a message is printed on standard error and unfsd exits with status 1. vibe check for your config ✨

🌈 SIGNALS 🌈

  • SIGTERM and SIGINT — will cause unfsd to unregister itself from the portmapper and exit. bye bestie 💅
  • SIGHUP — will cause unfsd to re-read its configuration data. Currently, this means the program queries 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. so like, fix it and poke her again 🫶
  • SIGUSR1 — will cause unfsd to output statistics about its filehandle and file descriptor cache to the system log. For the filehandle cache, it outputs 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 outputs the number of currently held open READ and WRITE file descriptors. numbers girlies rise 🎀

💅 EXPORTS FILE 💅

The exports file — /etc/exports by default — is basically the VIP list that decides which directories on the server NFS clients are allowed to access. Here’s an example, bestie:

# 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 — turns on root squashing, mapping all NFS requests done with a user id of 0 to the user id of the nobody user. This one is enabled by default, no cap.
  • no_root_squash — disables root squashing. When this 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 — squashes all users. When this is present, all NFS requests will be done as the nobody user of the server.
  • no_all_squash — does not squash all users. This option is enabled by default.
  • rw — allows read and write access on the exported directory. When this is present, clients are allowed to modify files and directories on the server.
  • ro — allows only read access on the exported directory. When this 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 — allows 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 — allows mount requests coming from any source port.
  • removable — considers 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 — considers this directory to be on a fixed medium. This option 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 📁

  • /etc/exports — the default exports file.

👑 AUTHOR 👑

Pascal Schmidt

🌈 SEE ALSO 🌈

Later, bestie — this unfsd(8) page is dated 05 Jan 2008 💖🎀✨

📦 where this page comes from