NFS(5)

📦
version 3.1.1 · 6 versions
, in arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💫 NFS(5) — File Formats Manual 💫

okay bestie, welcome to nfs(5), the manual page that explains the fstab format and options for nfs file systems. this is the one you want when you're hand-editing /etc/fstab at 2am and things are Not Going Well. grab a snack, we're doing this together 🍓

🌸 NAME 🌸

nfs — the fstab format and options for the nfs file systems. that's it, that's the name, short and sweet, main character energy ✨

🦋 SYNOPSIS 🦋

/etc/fstab

yes bestie, the whole synopsis is just a file path. iconic behavior honestly 👑

💖 DESCRIPTION 💖

okay so. NFS is an Internet Standard protocol, and it was created by Sun Microsystems back in 1984. that's older than most of us and it's still out here doing the most. the whole reason NFS exists is to let systems that live on the same local area network share files with each other. and depending on how your kernel is configured, the Linux NFS client might support NFS versions 3, 4.0, 4.1, or 4.2. no cap.

so the mount(8) command is what actually attaches a file system onto your system's name space hierarchy at some given mount point. and the /etc/fstab file is basically the group chat where all of that gets planned out — it describes how mount(8) should assemble your system's file name hierarchy out of all these various independent file systems, including the ones that NFS servers are exporting. every single line in /etc/fstab describes one file system, its mount point, and a set of default mount options for that mount point. one line, one filesystem, we love a clean structure.

for NFS file system mounts specifically, a line in /etc/fstab needs to specify:

  • the server name
  • the path name of the exported server directory you want to mount
  • the local directory that's gonna be the mount point
  • the type of file system being mounted
  • and a list of mount options that control how the filesystem gets mounted and how the NFS client acts when it's accessing files on that mount point

and here's a lil fun fact: the fifth and sixth fields on each line? NFS doesn't use them at all. so conventionally everybody just puts the digit zero in both. like, tradition 💅

for example:

server:path   /mountpoint   fstype   option,option,...   0 0

so the server's hostname and the export pathname get separated by a colon, the mount options get separated by commas, and all the remaining fields get separated by blanks or tabs. easy.

now, the server's hostname can be a bunch of different things, and this part matters:

  • an unqualified hostname
  • a fully qualified domain name
  • a dotted quad IPv4 address
  • an IPv6 address — but it has to be enclosed in square brackets

and listen, link-local and site-local IPv6 addresses must be accompanied by an interface identifier. that's not optional. if you wanna know the details on how to specify raw IPv6 addresses, go check ipv6(7).

the fstype field contains "nfs". and heads up — using the "nfs4" fstype in /etc/fstab is deprecated. so like, don't. 🙈

✨ MOUNT OPTIONS ✨

first things first: go look at mount(8) for a description of the generic mount options that are available for all file systems, not just NFS. and if you genuinely don't need to specify any mount options at all, just use the generic option defaults in /etc/fstab. sometimes the simplest route is the slayest route.

🎀 Options supported by all versions 🎀

these options are valid to use with any NFS version. no version gatekeeping here, we're inclusive.

  • nfsvers=n — the NFS protocol version number used to contact the server's NFS service. if the server doesn't support the version you asked for, the mount request fails, full stop. and if you don't specify this option at all, the client tries version 4.2 first, then negotiates down until it finds a version the server actually supports. it's giving "I'll meet you where you're at" energy 🫶
  • vers=n — this option is an alternative to the nfsvers option. it's included for compatibility with other operating systems. that's literally its whole deal.
  • soft / softerr / hard — this one determines the recovery behavior of the NFS client after an NFS request times out. so if no option is specified, or if the hard option is specified, NFS requests get retried indefinitely. but if either the soft or softerr option is specified, then the NFS client fails an NFS request after retrans retransmissions have been sent, which causes the NFS client to return either the error EIO (for the soft option) or ETIMEDOUT (for the softerr option) to the calling application.
NB: a so-called "soft" timeout can cause silent data corruption in certain cases. as such, use the soft or softerr option only when client responsiveness is more important than data integrity. and ngl, using NFS over TCP or increasing the value of the retrans option may mitigate some of the risks of using soft or softerr. 😭
  • softreval / nosoftreval — so in cases where the NFS server is down, it may be useful to let the NFS client keep serving up paths and attributes from cache after retrans attempts to revalidate that cache have timed out. this can be helpful, for instance, when you're trying to unmount a filesystem tree from a server that is permanently down. rip to that server but different. 💀

it's possible to combine softreval with the soft mount option, and in that case operations that cannot be served up from cache will time out and return an error after retrans attempts. the combination with the default hard mount option implies those uncached operations will just keep retrying until a response is received from the server. stubborn, honestly.

Note: the default mount option is nosoftreval, which disallows fallback to cache when revalidation fails, and instead follows the behavior dictated by the hard or soft mount option.
  • intr / nointr — this option is provided for backward compatibility. it is ignored after kernel 2.6.25. so if you're on a modern kernel, it's just vibing there doing nothing. 🙈
  • timeo=n — the time in deciseconds (tenths of a second) that the NFS client waits for a response before it retries an NFS request. okay so, for NFS over TCP the default timeo value is 600 (that's 60 seconds). the NFS client performs linear backoff here: after each retransmission, the timeout is increased by timeo up to a maximum of 600 seconds.

however — and this is the part where it gets spicy — for NFS over UDP, the client uses an adaptive algorithm to estimate an appropriate timeout value for frequently used request types (things like READ and WRITE requests), but it uses the timeo setting for infrequently used request types (things like FSINFO requests). if the timeo option is not specified, infrequently used request types are retried after 1.1 seconds. after each retransmission, the NFS client doubles the timeout for that request, up to a maximum timeout length of 60 seconds.

and any timeo value greater than the default value will be set to the default value. for TCP and RDMA, the default value is 600 (60 seconds). for UDP, the default value is 60 (6 seconds). so don't come in here thinking you can go bigger, because you cannot. 💅

  • retrans=n — the number of times the NFS client retries a request before it attempts further recovery action. if the retrans option is not specified, the NFS client tries each UDP request three times and each TCP request twice. the NFS client generates a "server not responding" message after retrans retries, then attempts further recovery — and what that recovery looks like depends on whether the hard mount option is in effect. 👑
  • rsize=n — the maximum number of bytes in each network READ request that the NFS client can receive when reading data from a file on an NFS server. the actual data payload size of each NFS READ request is equal to or smaller than the rsize setting. the largest read payload supported by the Linux NFS client is 1,048,576 bytes (one megabyte). big.

so the allowed rsize value is a positive integral multiple of the system's page size, or a power of two if it's less than the system's page size. specified rsize values lower than 1024 are replaced with 4096; values larger than 1048576 are replaced with 1048576. and if a specified value is within the supported range but isn't one of those allowed values, it gets rounded down to the nearest allowed value. sorry bestie, we're rounding. 🎀

if an rsize value is not specified, or if the specified rsize value is larger than the maximum that either client or server can support, the client and server negotiate the largest rsize value that they can both support. teamwork!

and here's the lil gotcha: the rsize mount option as specified on the mount(8) command line appears in the /etc/mtab file. however, the effective rsize value negotiated by the client and server is reported in the /proc/mounts file. so those two files can absolutely disagree with each other, and that's just how it is. ✨

  • wsize=n — the maximum number of bytes per network WRITE request that the NFS client can send when writing data to a file on an NFS server. the actual data payload size of each NFS WRITE request is equal to or smaller than the wsize setting. the largest write payload supported by the Linux NFS client is 1,048,576 bytes (one megabyte). same energy as rsize, just the other direction.

similar to rsize, the allowed wsize value is a positive integral multiple of the system's page size, or a power of two if it's less than the system's page size. specified wsize values lower than 1024 are replaced with 4096; values larger than 1048576 are replaced with 1048576. if a specified value is within the supported range but isn't such an allowed value, it gets rounded down to the nearest allowed value.

if a wsize value is not specified, or if the specified wsize value is larger than the maximum that either client or server can support, the client and server negotiate the largest wsize value that they can both support.

and yeah, same deal as before: the wsize mount option as specified on the mount(8) command line appears in the /etc/mtab file. however, the effective wsize value negotiated by the client and server is reported in the /proc/mounts file. 👀

  • ac / noac — selects whether the client may cache file attributes. if neither option is specified (or if ac is specified), the client caches file attributes.

so to improve performance, NFS clients cache file attributes. every few seconds, an NFS client checks the server's version of each file's attributes for updates. but changes that happen on the server during those small intervals remain undetected until the client checks the server again. the noac option prevents clients from caching file attributes so that applications can more quickly detect file changes on the server. so like, if freshness matters more to you than speed, that's your girl. 🌸

more parts coming, don't go anywhere bestie 💜

Okay so noac isn't just about not caching file attributes — it also forces application writes to go synchronous, so your local changes hit the server immediately. That way other clients can spot recent writes fast when they check the file's attributes. 💅

Using noac gives you greater cache coherence among NFS clients sharing the same files, but bestie, it comes with a significant performance penalty. So instead, the move is to use file locking judiciously. The DATA AND METADATA COHERENCE section has the full trade-off tea. 🍵

  • acregmin=n — the minimum time (in seconds) that the NFS client caches attributes of a regular file before it asks the server for fresh attribute info. If you don't set this, the client uses a 3-second minimum. See DATA AND METADATA COHERENCE for the whole attribute-caching saga.
  • acregmax=n — the maximum time (in seconds) that the NFS client caches attributes of a regular file before it asks the server for fresh attribute info. If you don't set this, the client uses a 60-second maximum. See DATA AND METADATA COHERENCE for the full discussion.
  • acdirmin=n — the minimum time (in seconds) that the NFS client caches attributes of a directory before it asks the server for fresh attribute info. If you don't set this, the client uses a 30-second minimum. See DATA AND METADATA COHERENCE for the full discussion.
  • acdirmax=n — the maximum time (in seconds) that the NFS client caches attributes of a directory before it asks the server for fresh attribute info. If you don't set this, the client uses a 60-second maximum. See DATA AND METADATA COHERENCE for the full discussion.
  • actimeo=n — using actimeo sets all of acregmin, acregmax, acdirmin, and acdirmax to the same value. If you don't set this, the NFS client uses the defaults for each of those options listed above.
  • bg / fg — decides how the mount(8) command acts if an attempt to mount an export fails. The fg option makes mount(8) exit with an error status if any part of the mount request times out or fails outright. That's called a "foreground" mount, and it's the default behavior if neither fg nor bg is specified.

If the bg option is specified, a timeout or failure makes mount(8) fork a child that keeps trying to mount the export. The parent immediately returns with a zero exit code. That's known as a "background" mount. ✨

If the local mount point directory is missing, mount(8) acts as if the mount request timed out. This lets nested NFS mounts specified in /etc/fstab proceed in any order during system initialization, even if some NFS servers aren't available yet. Or you can handle those issues with an automounter (see automount(8) for details).

  • nconnect=n — when you're using a connection-oriented protocol like TCP, it can lowkey be advantageous to set up multiple connections between client and server. For instance, if your clients and/or servers have multiple network interface cards (NICs), using multiple connections to spread the load may improve overall performance. In those cases, nconnect lets you specify the number of connections to establish between client and server, up to a limit of 16. 🦋

Note that some pNFS drivers may also use the nconnect option to decide how many connections to set up to the data servers.

  • rdirplus / nordirplus — picks whether to use NFS v3 or v4 READDIRPLUS requests. If you don't specify this, the NFS client uses a heuristic to optimize performance by choosing READDIR vs READDIRPLUS based on how often the calling process uses the additional attributes returned from READDIRPLUS. Some applications perform better if the client uses only READDIR requests for all directories.
  • rdirplus={none|force} — if set to "force", the NFS client always attempts to use READDIRPLUS requests. If set to "none", the behavior is the same as nordirplus.
  • retry=n — the number of minutes that the mount(8) command retries an NFS mount operation in the foreground or background before giving up. If you don't set this, the default for foreground mounts is 2 minutes, and the default for background mounts is 10000 minutes (that's 80 minutes shy of one week, bestie 😭). If you set it to zero, mount(8) exits immediately after the first failure.

Note that this only affects how many retries are made and doesn't affect the delay caused by each retry. For UDP, each retry takes the time determined by the timeo and retrans options, which by default will be about 7 seconds. For TCP the default is 3 minutes, but system TCP connection timeouts will sometimes limit the timeout of each retransmission to around 2 minutes.

  • sec=flavors — a colon-separated list of one or more security flavors to use for accessing files on the mounted export. If the server doesn't support any of these flavors, the mount operation fails. If sec= isn't specified, the client attempts to find a security flavor that both the client and the server support. Valid flavors are none, sys, krb5, krb5i, and krb5p. Refer to the SECURITY CONSIDERATIONS section for details. 🔐
  • sharecache / nosharecache — determines how the client's data cache and attribute cache are shared when mounting the same export more than once concurrently. Using the same cache reduces memory requirements on the client and presents identical file contents to applications when the same remote file is accessed via different mount points. 🫶

If neither option is specified, or if sharecache is specified, then a single cache is used for all mount points that access the same export. If nosharecache is specified, then that mount point gets a unique cache. Note that when data and attribute caches are shared, the mount options from the first mount point take effect for subsequent concurrent mounts of the same export.

As of kernel 2.6.18, the behavior specified by nosharecache is legacy caching behavior. This is considered a data risk since multiple cached copies of the same file on the same client can become out of sync following a local update of one of the copies. 💀

  • resvport / noresvport — specifies whether the NFS client should use a privileged source port when communicating with an NFS server for this mount point. If this option isn't specified, or if resvport is specified, the NFS client uses a privileged source port. If noresvport is specified, the NFS client uses a non-privileged source port. This option is supported in kernels 2.6.28 and later. ✨

Using non-privileged source ports helps increase the maximum number of NFS mount points allowed on a client, but NFS servers must be configured to allow clients to connect via non-privileged source ports.

Refer to the SECURITY CONSIDERATIONS section for important details.

  • lookupcache=mode — specifies how the kernel manages its cache of directory entries for a given mount point. mode can be one of all, none, pos, or positive. This option is supported in kernels 2.6.28 and later. 🌈

The Linux NFS client caches the result of all NFS LOOKUP requests. If the requested directory entry exists on the server, the result is referred to as positive. If the requested directory entry does not exist on the server, the result is referred to as negative.

If this option isn't specified, or if all is specified, the client assumes both types of directory cache entries are valid until their parent directory's cached attributes expire.

If pos or positive is specified, the client assumes positive entries are valid until their parent directory's cached attributes expire, but always revalidates negative entries before an application can use them.

If none is specified, the client revalidates both types of directory cache entries before an application can use them. This permits quick detection of files that were created or removed by other clients, but can impact application and server performance.

The DATA AND METADATA COHERENCE section contains a detailed discussion of these trade-offs.

  • fsc / nofsc — turns the caching of (read-only) data pages to your local disk on or off, using the FS-Cache facility ✨. Wanna know how to actually set that whole thing up? Go read cachefilesd(8) and peep <kernel_source>/Documentation/filesystems/caching 💖. Default is nofsc, so no caching unless you say so.
  • sloppy — bestie this one's just a lil shortcut: it's an alternative to passing mount.nfs -s 🎀.
  • xprtsec=policy — says "hey, use transport layer security to protect this mount point's NFS network traffic, k?" 🛡️ and policy can be one of none, tls, or mtls.
    • If you say none, transport layer security is forced off, even if the server supports it 🙅.
    • If you say tls, the client uses RPC-with-TLS to give you in-transit confidentiality 🔒.
    • If you say mtls, the client uses RPC-with-TLS to authenticate itself and give you in-transit confidentiality 🔐.
    • If you pick either tls or mtls and the server doesn't support RPC-with-TLS, or peer authentication fails? The mount attempt fails. Periodt 💀.
    • And if you don't specify the xprtsec= option at all, the default behavior depends on the kernel version, but it's usually equivalent to xprtsec=none 🦋.
  • noalignwrite — this disables the default behavior of stretching buffered write operations out to full page boundaries 📏.

Normally, the NFS client rounds non-aligned buffered writes up to the system page size, which can cause "lost writes" when multiple clients write concurrently to distinct, non-overlapping regions 😭. So use this option when your apps do non-aligned buffered writes and you can guarantee the file regions don't overlap — that way you dodge the whole file locking situation 🫶.

✨ Options for NFS versions 2 and 3 only ✨

Okay so use these options — along with the options in the subsection above — for NFS versions 2 and 3 only, no cap 💅.

  • proto=netid — the netid decides which transport talks to the NFS server 🌈. Your choices are udp, udp6, tcp, tcp6, rdma, and rdma6. The ones ending in 6 use IPv6 addresses and only work if support for TI-RPC is built in; the others use IPv4 addresses.

Every transport protocol comes with different default retrans and timeo settings, so go read those two mount options if you want the tea ☕.

And it's not just about how the NFS client sends requests, bestie — this mount option also controls how the mount(8) command talks to the server's rpcbind and mountd services 👀. Pick a netid that uses TCP and all traffic from mount(8) and the NFS client gets forced onto TCP. Pick one that uses UDP and all traffic types get forced onto UDP.

Before you go running NFS over UDP, go read the TRANSPORT METHODS section, fr fr.

If you don't specify the proto mount option, mount(8) figures out which protocols the server supports and picks an appropriate transport for each service 🧚. More deets in TRANSPORT METHODS.

  • udp — this is just another way of saying proto=udp 💜. It's included for compatibility with other operating systems.

Again: before using NFS over UDP, read the TRANSPORT METHODS section ⚠️.

  • tcp — alternative to specifying proto=tcp, included for compatibility with other operating systems 💫.
  • rdma — alternative to specifying proto=rdma 🚀.
  • port=n — the numeric value of the server's NFS service port 🔢. If the server's NFS service isn't available on that port, the mount request fails.

If you don't specify this option, or if the value you give is 0, then the NFS client uses the NFS service port number advertised by the server's rpcbind service 🍓. And the mount request fails if: the server's rpcbind service isn't available, the server's NFS service isn't registered with its rpcbind service, or the server's NFS service isn't available on the advertised port. Rough 😭.

  • mountport=n — the numeric value of the server's mountd port 🔢. If the server's mountd service isn't available on the specified port, the mount request fails.

If you don't specify it, or the value is 0, then mount(8) uses the mountd service port number advertised by the server's rpcbind service 🌸. Mount request fails if: rpcbind isn't available, mountd isn't registered with its rpcbind service, or mountd isn't available on the advertised port.

Lowkey iconic use case: this option is here for when you're mounting an NFS server through a firewall that blocks the rpcbind protocol 🔥.

  • mountproto=netid — the transport the NFS client uses to send requests to the NFS server's mountd service while doing this mount request, and also when it later unmounts this mount point 🚚.

netid can be one of udp and tcp, which use IPv4 addresses, or — if TI-RPC is built into the mount.nfs command — udp6 and tcp6, which use IPv6 addresses 💅.

Use this when mounting an NFS server through a firewall that blocks a particular transport 🧱. And when you pair it with the proto option, you can specify different transports for mountd requests and NFS requests 🎯. If the server's mountd service isn't available via the specified transport, the mount request fails.

Wanna know how mountproto and proto interact? That's all in the TRANSPORT METHODS section, go look 👑

  • mounthost=name — the hostname of the host running mountd 🏠. If you don't specify it, mount(8) just assumes mountd runs on the same host as the NFS service.
  • mountvers=n — the RPC version number used to contact the server's mountd 🔢. If you don't specify it, the client uses a version number appropriate to the requested NFS version. Super handy when multiple NFS services are running on the same remote server host 👯.
  • namlen=n — the maximum length of a pathname component on this mount 📝. If you don't specify it, the maximum length gets negotiated with the server, and in most cases that max is 255 characters.

Some early versions of NFS didn't support this negotiation 🙈. Using this option makes sure pathconf(3) reports the proper maximum component length to applications in those cases.

  • lock / nolock — picks whether to use the NLM sideband protocol to lock files on the server 🔐. If neither option is specified (or if lock is specified), NLM locking is used for this mount point. With nolock, applications can lock files, but those locks only provide exclusion against other applications running on the same client — remote applications aren't affected by them at all 🙅.
Heads up bestie: NLM locking must be disabled with nolock when you're using NFS to mount /var, because /var contains files used by the NLM implementation on Linux 💀. And you also need nolock when mounting exports on NFS servers that don't support the NLM protocol.
  • cto / nocto — picks whether to use close-to-open cache coherence semantics 🚪👀. If neither is specified (or if cto is specified), the client uses close-to-open cache coherence semantics. If you specify nocto, the client uses a non-standard heuristic to figure out when files on the server have changed.

nocto might improve performance for read-only mounts, but only use it if the data on the server changes only occasionally 😬. The DATA AND METADATA COHERENCE section goes deeper on this one.

  • acl / noacl — picks whether to use the NFSACL sideband protocol on this mount point 🎀. NFSACL is a proprietary protocol implemented in Solaris that manages Access Control Lists, and ngl it was never made a standard part of the NFS protocol specification 😔.

If you specify neither acl nor noacl, the NFS client negotiates with the server to see if NFSACL is supported, and uses it if the server does 🤝. Disabling the NFSACL sideband protocol may be necessary if the negotiation causes problems on the client or server. Peep the SECURITY CONSIDERATIONS section for more deets.

  • local_lock=mechanism — specifies whether to use local locking for any or both of the flock and the POSIX locking mechanisms 🧩. mechanism can be one of all, flock, posix, or none. This option is supported in kernels 2.6.37 and later ⭐.

The Linux NFS client gives you a way to make locks local 🏡. Meaning: applications can lock files, but those locks only provide exclusion against other applications running on the same client. Remote applications are not affected by these locks, periodt 💅.

  • If you don't set this option at all, or you set none, the client just assumes the locks are not local.
  • all — the client assumes that both flock and POSIX locks are local.
  • flock — the client assumes that only flock locks are local, and it uses the NLM sideband protocol to lock files whenever POSIX locks are used.
  • posix — the client assumes that POSIX locks are local, and it uses the NLM sideband protocol to lock files whenever flock locks are used.

Wanna support that legacy flock behavior, the kind NFS clients < 2.6.12 had? Use local_lock=flock. Bestie, this option is required when you're exporting NFS mounts via Samba, because Samba maps Windows share mode locks as flock. And here's the tea: since NFS clients > 2.6.12 implement flock by emulating POSIX locks, this is gonna give you conflicting locks. 😭

NOTE: when you use them together, the local_lock mount option gets overridden by the nolock/lock mount option. So like, don't be surprised. 💀

✨ Options for NFS version 4 only ✨

Use these ones, plus everything in the first subsection up there, for NFS version 4.0 and newer. 🦋

  • proto=netid — the netid decides which transport talks to the NFS server. Supported: tcp, tcp6, rdma, and rdma6. tcp6 uses IPv6 addresses and is only available if support for TI-RPC is built in. Both of the others use IPv4 addresses.

All NFS version 4 servers are required to support TCP, so if you don't specify this mount option, the NFS version 4 client just uses the TCP protocol. Peep the TRANSPORT METHODS section for more details. 👑

  • minorversion=n — sets the protocol minor version number. NFSv4 brought in "minor versioning," where NFS protocol enhancements can be added without bumping the NFS protocol version number. Before kernel 2.6.38, the minor version is always zero and this option is not recognized. After that kernel, specifying minorversion=1 turns on a bunch of advanced features, like NFSv4 sessions. ✨

Recent kernels let you specify the minor version with the vers= option. For example, vers=4.1 is the same as vers=4,minorversion=1. 💅

  • port=n — the numeric value of the server's NFS service port. If the server's NFS service isn't available on the port you specified, the mount request fails.

If you don't specify this mount option, the NFS client uses the standard NFS port number 2049 without first checking the server's rpcbind service. This lets an NFS version 4 client reach an NFS version 4 server through a firewall that might block rpcbind requests. 🔥

If the specified port value is 0, then the NFS client uses the NFS service port number advertised by the server's rpcbind service. The mount request fails if the server's rpcbind service isn't available, if the server's NFS service isn't registered with its rpcbind service, or if the server's NFS service isn't available on the advertised port. 🫠

  • cto / nocto — picks whether to use close-to-open cache coherence semantics for NFS directories on this mount point. If you specify neither cto nor nocto, the default is to use close-to-open cache coherence semantics for directories.

File data caching behavior is not affected by this option. The DATA AND METADATA COHERENCE section spills the details on how this one behaves. 🎀

  • clientaddr=n.n.n.n
  • clientaddr=n:n:...:n — specifies a single IPv4 address (in dotted-quad form), or a non-link-local IPv6 address, that the NFS client advertises so servers can do NFS version 4.0 callback requests against files on this mount point. If the server can't establish callback connections to clients, performance may degrade, or accesses to files may temporarily hang. You can specify a value of IPv4_ANY (0.0.0.0) or an equivalent IPv6 any address, which signals to the NFS server that this NFS client does not want delegations.

If you don't specify this option, the mount(8) command tries to discover an appropriate callback address automatically. The automatic discovery process isn't perfect though, fr fr. With multiple client network interfaces, special routing policies, or atypical network topologies, figuring out the exact address to use for callbacks can be nontrivial. 😮‍💨

NFS protocol versions 4.1 and 4.2 use the client-established TCP connection for callback requests, so they don't need the server to connect to the client. This option therefore only affects NFS version 4.0 mounts. ⭐

  • migration / nomigration — picks whether the client uses an identification string that's compatible with NFSv4 Transparent State Migration (TSM). If the mounted server supports NFSv4 migration with TSM, go ahead and specify the migration option.

Some server features misbehave in the face of a migration-compatible identification string. The nomigration option keeps using a traditional client identification string, which is compatible with legacy NFS servers. That's also the behavior if you specify neither option. Heads up though: a client's open and lock state cannot be migrated transparently when it identifies itself via a traditional identification string. 🙈

This mount option has no effect with NFSv4 minor versions newer than zero, which always use TSM-compatible client identification strings.

  • max_connect=n — while the nconnect option sets a limit on the number of connections that can be established to a given server IP, max_connect lets you specify the maximum number of connections to different server IPs that belong to the same NFSv4.1+ server (session trunkable connections), up to a limit of 16. When the client discovers that it established a client ID to an already existing server, instead of dropping the newly created network transport, it adds this new connection to the list of available transports for that RPC client. 🧚
  • trunkdiscovery / notrunkdiscovery — when the client discovers a new filesystem on an NFSv4.1+ server, the trunkdiscovery mount option makes it send a GETATTR for the fs_locations attribute. If it receives a non-zero length reply, it iterates through the response, and for each server location it establishes a connection, sends an EXCHANGE_ID, and tests for session trunking. If the trunking test succeeds, the connection gets added to the existing set of transports for the server, subject to the limit specified by the max_connect option. The default is notrunkdiscovery. 🌈

🌸 nfs4 FILE SYSTEM TYPE 🌸

The nfs4 file system type is an old syntax for specifying NFSv4 usage. You can still use it with all NFSv4-specific and common options — except the nfsvers mount option. 👑

🎀 MOUNT CONFIGURATION FILE 🎀

If the mount command is configured to do so, all of the mount options described in the previous section can also be configured in the /etc/nfsmount.conf file. See nfsmount.conf(5) for the deets. 💖

✨ EXAMPLES ✨

To mount using NFS version 3, use the nfs file system type and specify the nfsvers=3 mount option. To mount using NFS version 4, use either the nfs file system type with the nfsvers=4 mount option, or the nfs4 file system type. 💅

The following example from an /etc/fstab file makes the mount command negotiate reasonable defaults for NFS behavior. 🦋

server:/export  /mnt  nfs   defaults                      0 0

This example shows how to mount using NFS version 4 over TCP with Kerberos 5 mutual authentication. 🔥

server:/export  /mnt  nfs4  sec=krb5                      0 0

This example shows how to mount using NFS version 4 over TCP with Kerberos 5 privacy or data integrity mode. 🔐

server:/export  /mnt  nfs4  sec=krb5p:krb5i               0 0

This example can be used to mount /usr over NFS. 👑

server:/export  /usr  nfs   ro,nolock,nocto,actimeo=3600  0 0

This example shows how to mount an NFS server using a raw IPv6 link-local address. ⭐

[fe80::215:c5ff:fb3e:e2b1%eth0]:/export /mnt nfs defaults 0 0

🌐 TRANSPORT METHODS 🌐

okay so bestie, NFS clients don't just shout at servers, they slide into their DMs via Remote Procedure Calls, aka RPCs. and the RPC client is out here doing the most, in the best way 💅:

  • it discovers remote service endpoints automatically (no manual labor, we love that)
  • it handles per-request authentication
  • it adjusts request parameters for different byte endianness</> on client vs server (yes they can disagree, it's fine)
  • and it retransmits requests that the network or server may have fumbled

and all of that flows over a network transport. like, the whole vibe rides on top of it. 🦋

most of the time? the mount(8) command, the NFS client, and the NFS server all just automatically negotiate the right transport and data transfer size settings for a mount point. it's giving teamwork. but sometimes you lowkey do need to specify these settings explicitly with mount options, and that's when you step in as the main character. 👑

so, history lesson 🎀: NFS clients traditionally used the UDP transport exclusively to send requests to servers. and yeah, the implementation is simple, that's true, but NFS over UDP has so many limitations that stop it from operating smoothly or performing well in some super common deployment environments. even a teeny-tiny insignificant packet loss rate means you lose whole NFS requests — an entire request, gone, bye. so retransmit timeouts are usually in the subsecond range to let clients recover fast from dropped requests. but that can cause extra network traffic and server load. it's giving "fixing it made it worse." 😭

but ngl, UDP can actually be pretty effective in specialized settings where the network's MTU is large relative to NFS's data transfer size — think network environments that enable jumbo Ethernet frames. in those setups, you're advised to trim the rsize and wsize settings so each NFS read or write request fits in just a few network frames, or even in a single frame. this lowers the odds that losing one single MTU-sized network frame kills an entire big read or write request. strategy! 🧠✨

TCP is the default transport protocol for all modern NFS implementations. it performs well in basically every conceivable network environment and gives excellent guarantees against data corruption caused by network unreliability. it's the moment. also, TCP is often a requirement for mounting a server through a network firewall. 🔥

under normal circumstances, networks drop packets way more often than NFS servers drop requests. so an aggressive retransmit timeout setting for NFS over TCP is just unnecessary drama. typical timeout settings for NFS over TCP are between one and ten minutes. once the client exhausts its retransmits (that's the value of the retrans mount option), it assumes a network partition happened and tries to reconnect to the server on a fresh socket. and since TCP itself makes network data transfer reliable, rsize and wsize can safely default to the largest values supported by both client and server — independent of the network's MTU size. slay. 💅

🔌 Using the mountproto mount option 🔌

heads up, this section applies only to NFS version 3 mounts, because NFS version 4 doesn't use a separate protocol for mount requests. NFSv4 said "we're not doing that anymore" and honestly, iconic behavior.

the Linux NFS client can use a different transport for contacting an NFS server's rpcbind service, its mountd service, its Network Lock Manager (NLM) service, and its NFS service. the exact transports the Linux NFS client uses for each mount point depends on the settings of the transport mount options, which include proto, mountproto, udp, and tcp.

the client sends Network Status Manager (NSM) notifications via UDP no matter what transport options you specify — it does not care, it's sending them over UDP — but it listens for server NSM notifications on both UDP and TCP. and the NFS Access Control List (NFSACL) protocol shares the same transport as the main NFS service. they're matching outfits, basically. 🎀

if no transport options are specified, the Linux NFS client uses UDP to contact the server's mountd service, and TCP to contact its NLM and NFS services, by default.

if the server doesn't support these transports for these services, the mount(8) command tries to discover what the server does support, and then retries the mount request once using the discovered transports. if the server doesn't advertise any transport the client supports, or if it's misconfigured, the mount request fails. 💀 and if the bg option is in effect, the mount command backgrounds itself and keeps attempting the specified mount request.

  • if the proto option, the udp option, or the tcp option is specified but mountproto is not, then the specified transport is used to contact both the server's mountd service and the NLM and NFS services.
  • if mountproto is specified but none of proto, udp or tcp are, then the specified transport is used for the initial mountd request, but the mount command attempts to discover what the server supports for the NFS protocol, preferring TCP if both transports are supported.
  • if both mountproto and proto (or udp or tcp) are specified, then the transport specified by mountproto is used for the initial mountd request, and the transport specified by proto (or the udp or tcp options) is used for NFS — no matter what order these options appear. and no automatic service discovery is performed if these options are specified. you asked for it, you got it, no takebacks.
  • if any of the proto, udp, tcp, or mountproto options are specified more than once on the same mount command line, then the value of the rightmost instance of each of these options takes effect. last one wins, periodt. ✨
Using NFS over UDP on high-speed links such as Gigabit can cause silent data corruption.

not me being dramatic, this is literally the manpage talking. 😭 silent data corruption is the scariest kind because it doesn't announce itself. it's just there, ruining your files, minding its own business.

so the problem can be triggered at high loads, and it's caused by problems in IP fragment reassembly. NFS reads and writes typically transmit UDP packets of 4 Kilobytes or more, which have to be broken up into several fragments to be sent over the Ethernet link, which limits packets to 1500 bytes by default. this happens at the IP network layer and it's called fragmentation.

in order to identify fragments that belong together, IP assigns a 16bit IP ID value to each packet; fragments generated from the same UDP packet will have the same IP ID. the receiving system collects these fragments and combines them to form the original UDP packet. this process is called reassembly. the default timeout for packet reassembly is 30 seconds; if the network stack doesn't receive all fragments of a given packet within that interval, it assumes the missing fragment(s) got lost and discards the ones it already received. bye bestie. 🫶

the problem this creates over high-speed links is that it's possible to send more than 65536 packets within 30 seconds. in fact, with heavy NFS traffic you can observe that the IP IDs repeat after about 5 seconds. yeah. that's fast.

this has serious effects on reassembly: if one fragment gets lost, another fragment from a different packet but with the same IP ID will arrive within the 30 second timeout, and the network stack will combine these fragments to form a new packet. most of the time, network layers above IP will detect this mismatched reassembly — in the case of UDP, the UDP checksum, which is a 16 bit checksum over the entire packet payload, will usually not match, and UDP will discard the bad packet. good job UDP, thank you for your service. 🎀

but — and this is the scary part — the UDP checksum is 16 bit only, so there's a chance of 1 in 65536 that it will match even if the packet payload is completely random (which very often isn't the case). and if that happens? silent data corruption will occur. 💀💀💀

this potential should be taken seriously, at least on Gigabit Ethernet. network speeds of 100Mbit/s should be considered less problematic, because with most traffic patterns IP ID wrap around will take much longer than 30 seconds. phew.

it is therefore strongly recommended to use NFS over TCP where possible, since TCP does not perform fragmentation. TCP would never. ✨

if you absolutely have to use NFS over UDP over Gigabit Ethernet, some steps can be taken to mitigate the problem and reduce the probability of corruption:

  • Jumbo frames: many Gigabit network cards are capable of transmitting frames bigger than the 1500 byte limit of traditional Ethernet, typically 9000 bytes. using jumbo frames of 9000 bytes will allow you to run NFS over UDP at a page size of 8K without fragmentation. of course, this is only feasible if all involved stations support jumbo frames. no halfsies.

to enable a machine to send jumbo frames on cards that support it, it's sufficient to configure the interface for a MTU value of 9000.

  • Lower reassembly timeout: by lowering this timeout below the time it takes the IP ID counter to wrap around, incorrect reassembly of fragments can be prevented as well. to do so, simply write the new timeout value (in seconds) to the file /proc/sys/net/ipv4/ipfrag_time.

a value of 2 seconds will greatly reduce the probability of IPID clashes on a single Gigabit link, while still allowing for a reasonable timeout when receiving fragmented traffic from distant peers.

🔄 DATA AND METADATA COHERENCE 🔄

some modern cluster file systems provide perfect cache coherence among their clients. and like, perfect cache coherence among disparate NFS clients is expensive to achieve, especially on wide area networks. it's giving "sure, if you want to pay for it." so NFS settles for weaker cache coherence that satisfies the requirements of most file sharing types. reasonable queen behavior. 👑

🌸 Close-to-open cache consistency 🌸

typically, file sharing is completely sequential. first client A opens a file, writes something to it, then closes it. then client B opens the same file, and reads the changes. nice and tidy, a little relay race. 🏃♀️

when an application opens a file stored on an NFS version 3 server, the NFS client checks that the file exists on the server and is permitted to the opener by sending a GETATTR or ACCESS request. and it sends these requests regardless of the freshness of the file's cached attributes. it doesn't trust the cache, it verifies. paranoid but make it cute. 🙈

when the application closes the file, the NFS client writes back any pending changes to the file so the next opener can view the changes. this also gives the NFS client an opportunity to report write errors to the application via the return code from close(2). see, closing is doing work. respect it.

the behavior of checking at open time and flushing at close time is referred to as close-to-open cache consistency, or CTO. and it can be disabled for an entire mount point using the nocto mount option.

🦋 Weak cache consistency 🦋

there are still opportunities for a client's data cache to contain stale data. like, it's not perfect, bestie. but the NFS version 3 protocol introduced "weak cache consistency" (also known as WCC) which provides a way of efficiently checking a file's attributes before and after a single request. this allows a client to help identify changes that could have been made by other clients. teamwork makes the dream work. 💖

okay so when a client is out here running a whole bunch of concurrent ops that update the same file at the same time (think: asynchronous write behind, that whole vibe), it's still genuinely hard to tell whether it was that client's updates or some other client's updates that changed the file. 😭 messy.

✨ Attribute caching ✨

Use the noac mount option to get attribute cache coherence across multiple clients. Almost every file system operation peeks at file attribute info, and the client keeps that info cached for a while to cut down on network and server load. When noac is in effect, a client's file attribute cache is disabled, so every single operation that needs to check a file's attributes is forced to go all the way back to the server. That means a client sees changes to a file super quickly — at the cost of a whole lot of extra network operations. 💸

bestie, do NOT confuse the noac option with "no data caching." The noac mount option stops the client from caching file metadata, but there are still races that can leave data cache incoherence hanging between client and server. two different things, iykyk. 💅

The NFS protocol was not designed to support true cluster file system cache coherence without some type of application serialization. If you need absolute cache coherence among clients, applications should use file locking. Alternatively, applications can open their files with the O_DIRECT flag to disable data caching entirely. ✨

🎀 File timestamp maintenance 🎀

NFS servers are the ones responsible for managing file and directory timestamps (atime, ctime, and mtime). When a file is accessed or updated on an NFS server, that file's timestamps get updated just like they would on a filesystem local to an application.

NFS clients cache file attributes, timestamps included. A file's timestamps are updated on NFS clients when its attributes are retrieved from the NFS server. So yeah — there may be some delay before timestamp updates on an NFS server actually show up for applications on NFS clients. 🙈

To comply with the POSIX filesystem standard, the Linux NFS client relies on NFS servers to keep a file's mtime and ctime timestamps properly up to date. It does this by flushing local data changes to the server before reporting mtime to applications via system calls such as stat(2). 📝

The Linux client handles atime updates more loosely, though. NFS clients keep performance good by caching data, but that means application reads — which normally update atime — are not reflected to the server where a file's atime is actually maintained.

Because of this caching behavior, the Linux NFS client does not support generic atime-related mount options. See mount(8) for the details on those options.

In particular, the atime/noatime, diratime/nodiratime, relatime/norelatime, and strictatime/nostrictatime mount options have no effect on NFS mounts. zero. nada. 💀

/proc/mounts may report that the relatime mount option is set on NFS mounts, but in fact the atime semantics are always as described here, and are not like relatime semantics. don't let it gaslight you. 🫶

🦋 Directory entry caching 🦋

The Linux NFS client caches the result of all NFS LOOKUP requests. If the requested directory entry exists on the server, that result is called a positive lookup result. If the requested directory entry does not exist on the server (that is, the server returned ENOENT), that result is called a negative lookup result.

To detect when directory entries have been added or removed on the server, the Linux NFS client watches a directory's mtime. If the client detects a change in a directory's mtime, it drops all cached LOOKUP results for that directory. And since the directory's mtime is itself a cached attribute, it may take some time before a client notices it has changed. See the descriptions of the acdirmin, acdirmax, and noac mount options for more on how long a directory's mtime is cached. ⏳

Caching directory entries improves performance for applications that do not share files with applications on other clients. But using cached info about directories can interfere with applications that run concurrently on multiple clients and need to detect the creation or removal of files quickly. The lookupcache mount option lets you tune directory entry caching behavior a lil bit. 🎛️

Before kernel release 2.6.28, the Linux NFS client tracked only positive lookup results. That let applications detect new directory entries created by other clients quickly while still giving some of the performance benefits of caching. If an application depends on the previous lookup caching behavior of the Linux NFS client, you can use lookupcache=positive.

If the client ignores its cache and validates every application lookup request with the server, that client can immediately detect when a new directory entry has been either created or removed by another client. You can specify this behavior using lookupcache=none. The extra NFS requests needed when the client doesn't cache directory entries can exact a performance penalty — but disabling lookup caching should result in less of a performance penalty than using noac, and it has no effect on how the NFS client caches the attributes of files. 💅

🌈 The sync mount option 🌈

The NFS client treats the sync mount option differently than some other file systems do (refer to mount(8) for a description of the generic sync and async mount options). If neither sync nor async is specified (or if the async option is specified), the NFS client delays sending application writes to the server until any of these events occur:

  • Memory pressure forces reclamation of system memory resources.
  • An application flushes file data explicitly with sync(2), msync(2), or fsync(3).
  • An application closes a file with close(2).
  • The file is locked/unlocked via fcntl(2).

In other words, under normal circumstances, data written by an application may not immediately appear on the server that hosts the file. 😳 it's giving "eventually."

If the sync option is specified on a mount point, any system call that writes data to files on that mount point causes that data to be flushed to the server before the system call returns control to user space. This provides greater data cache coherence among clients, but at a significant performance cost. pick your fighter. ⚔️

Applications can use the O_SYNC open flag to force application writes to individual files to go to the server immediately, without using the sync mount option. 🔥

🔒 Using file locks with NFS 🔒

The Network Lock Manager protocol is a separate sideband protocol used to manage file locks in NFS version 3. To support lock recovery after a client or server reboot, a second sideband protocol — known as the Network Status Manager protocol — is also required. In NFS version 4, file locking is supported directly in the main NFS protocol, and the NLM and NSM sideband protocols are not used. slay, progress. 👑

In most cases, NLM and NSM services are started automatically, and no extra configuration is required. Configure all NFS clients with fully-qualified domain names to make sure NFS servers can find clients and notify them of server reboots. 📇

NLM supports advisory file locks only. To lock NFS files, use fcntl(2) with the F_GETLK and F_SETLK commands. The NFS client converts file locks obtained via flock(2) to advisory locks.

When mounting servers that do not support the NLM protocol, or when mounting an NFS server through a firewall that blocks the NLM service port, specify the nolock mount option. NLM locking must be disabled with the nolock option when using NFS to mount /var, because /var contains files used by the NLM implementation on Linux. ⚠️

Specifying the nolock option may also be advised to improve the performance of a proprietary application which runs on a single client and uses file locks extensively.

🧚 NFS version 4 caching features 🧚

The data and metadata caching behavior of NFS version 4 clients is similar to that of earlier versions. However, NFS version 4 adds two features that improve cache behavior: change attributes and file delegation. ✨

The change attribute is a new part of NFS file and directory metadata which tracks data changes. It replaces the use of a file's modification and change time stamps as a way for clients to validate the content of their caches. Change attributes are independent of the time stamp resolution on either the server or client, though. 🕰️

A file delegation is a contract between an NFS version 4 client and server that allows the client to treat a file temporarily as if no other client is accessing it. The server promises to notify the client (via a callback request) if another client attempts to access that file. Once a file has been delegated to a client, the client can cache that file's data and metadata aggressively without contacting the server. main character energy fr. 💅

File delegations come in two flavors: read and write. A read delegation means the server notifies the client about any other clients that want to write to the file. A write delegation means the client gets notified about either read or write accessors. 👀

Servers grant file delegations when a file is opened, and can recall delegations at any time when another client wants access to the file that conflicts with any delegations already granted. Delegations on directories are not supported.

In order to support delegation callback, the server checks the network return path to the client during the client's initial contact with the server. If contact with the client cannot be established, the server simply does not grant any delegations to that client. no callback route, no delegation, periodt. 💀

🔐 SECURITY CONSIDERATIONS 🔐

okay bestie, this is the part where we talk about who gets to touch what, and ngl it's kind of a lot. so like — NFS servers are the ones controlling access to file data, right? but they can't do it alone. they depend on their RPC implementation to provide authentication of NFS requests. that's the whole pipeline. 💅

traditional NFS access control mimics the standard mode bit access control you already know from local file systems. and traditional RPC authentication is... a whole vibe. it uses a number to represent each user (usually the user's own uid), a number to represent the user's group (the user's gid), and a set of up to 16 auxiliary group numbers to represent other groups of which the user may be a member. sixteen. that's the whole guest list.

typically, file data and user ID values appear unencrypted (i.e. "in the clear") on the network. like, out there. naked. 😭 and it gets worse: NFS versions 2 and 3 use separate sideband protocols for mounting, locking and unlocking files, and reporting system status of clients and servers. these auxiliary protocols use no authentication. none. zero. not a single vibe check. 💀

in addition to combining these sideband protocols with the main NFS protocol, NFS version 4 introduces more advanced forms of access control, authentication, and in-transit data protection. the NFS version 4 specification mandates support for strong authentication and security flavors that provide per-RPC integrity checking and encryption. and because NFS version 4 combines the function of the sideband protocols into the main NFS protocol, the new security features apply to all NFS version 4 operations including mounting, file locking, and so on. so the glow-up applies everywhere, periodt. ✨

RPCGSS authentication can also be used with NFS versions 2 and 3, but — and this is the important part — it does not protect their sideband protocols.

the sec mount option specifies the security flavor used for operations on behalf of users on that NFS mount point. specifying sec=krb5 provides cryptographic proof of a user's identity in each RPC request. that's strong verification of the identity of users accessing data on the server, fr fr. note that additional configuration besides adding this mount option is required in order to enable Kerberos security. refer to the rpc.gssd(8) man page for details. 🫶

two additional flavors of Kerberos security are supported: krb5i and krb5p.

  • krb5i — provides a cryptographically strong guarantee that the data in each RPC request has not been tampered with. 👑
  • krb5p — encrypts every RPC request to prevent data exposure during network transit. but bestie, expect some performance impact when using integrity checking or encryption. 💅

similar support for other forms of cryptographic security is also available.

🦋 NFS version 4 filesystem crossing 🦋

the NFS version 4 protocol allows a client to renegotiate the security flavor when the client crosses into a new filesystem on the server. the newly negotiated flavor effects only accesses of the new filesystem. it's giving "new neighborhood, new rules." ✨

such negotiation typically occurs when a client crosses from a server's pseudo-fs into one of the server's exported physical filesystems, which often have more restrictive security settings than the pseudo-fs.

🎀 NFS version 4 Leases 🎀

in NFS version 4, a lease is a period during which a server irrevocably grants a client file locks. once the lease expires, the server may revoke those locks. clients periodically renew their leases to prevent lock revocation. keep that lease alive, girl. 💖

after an NFS version 4 server reboots, each client tells the server about existing file open and lock state under its lease before operation can continue. and if a client reboots, the server frees all open and lock state associated with that client's lease. clean slate. 🧚

when establishing a lease, therefore, a client must identify itself to a server. each client presents an arbitrary string to distinguish itself from other clients. the client administrator can supplement the default identity string using the nfs4.nfs4_unique_id module parameter to avoid collisions with other client identity strings. no two besties with the same name energy. 💅

a client also uses a unique security flavor and principal when it establishes its lease. if two clients present the same identity string, a server can use client principals to distinguish between them, thus securely preventing one client from interfering with the other's lease. iconic, honestly. 👑

the Linux NFS client establishes one lease on each NFS version 4 server. lease management operations, such as lease renewal, are not done on behalf of a particular file, lock, user, or mount point, but on behalf of the client that owns that lease. a client uses a consistent identity string, security flavor, and principal across client reboots to ensure that the server can promptly reap expired lease state.

when Kerberos is configured on a Linux NFS client (i.e., there is a /etc/krb5.keytab on that client), the client attempts to use a Kerberos security flavor for its lease management operations. Kerberos provides secure authentication of each client. by default, the client uses the host/ or nfs/ service principal in its /etc/krb5.keytab for this purpose, as described in rpc.gssd(8).

if the client has Kerberos configured, but the server does not, or if the client does not have a keytab or the requisite service principals, the client uses AUTH_SYS and UID 0 for lease management. fallback behavior, we love her. 🙈

🔥 Using non-privileged source ports 🔥

NFS clients usually communicate with NFS servers via network sockets. each end of a socket is assigned a port value, which is simply a number between 1 and 65535 that distinguishes socket endpoints at the same IP address. a socket is uniquely defined by a tuple that includes the transport protocol (TCP or UDP) and the port values and IP addresses of both endpoints. it's a whole little identity card. 💜

the NFS client can choose any source port value for its sockets, but usually chooses a privileged port. a privileged port is a port value less than 1024. only a process with root privileges may create a socket with a privileged source port. ✨

the exact range of privileged source ports that can be chosen is set by a pair of sysctls to avoid choosing a well-known port, such as the port used by ssh. this means the number of source ports available for the NFS client, and therefore the number of socket connections that can be used at the same time, is practically limited to only a few hundred. 💀

as described above, the traditional default NFS authentication scheme, known as AUTH_SYS, relies on sending local UID and GID numbers to identify users making NFS requests. an NFS server assumes that if a connection comes from a privileged port, the UID and GID numbers in the NFS requests on this connection have been verified by the client's kernel or some other local authority. this is an easy system to spoof, but on a trusted physical network between trusted hosts, it is entirely adequate. not great, not terrible, as the kids say. 😭

roughly speaking, one socket is used for each NFS mount point. if a client could use non-privileged source ports as well, the number of sockets allowed, and thus the maximum number of concurrent mount points, would be much larger.

using non-privileged source ports may compromise server security somewhat, since any user on AUTH_SYS mount points can now pretend to be any other when making NFS requests. thus NFS servers do not support this by default. they explicitly allow it usually via an export option. ⚠️

to retain good security while allowing as many mount points as possible, it is best to allow non-privileged client connections only if the server and client both require strong authentication, such as Kerberos. mutual bestie trust. 🫶

🌈 Mounting through a firewall 🌈

a firewall may reside between an NFS client and server, or the client or server may block some of its own ports via IP filter rules. it is still possible to mount an NFS server through a firewall, though some of the mount(8) command's automatic service endpoint discovery mechanisms may not work; this requires you to provide specific endpoint details via NFS mount options. manual mode, babe. 💅

NFS servers normally run a portmapper or rpcbind daemon to advertise their service endpoints to clients. clients use the rpcbind daemon to determine:

  • what network port each RPC-based service is using
  • what transport protocols each RPC-based service supports

the rpcbind daemon uses a well-known port number (111) to help clients find a service endpoint. although NFS often uses a standard port number (2049), auxiliary services such as the NLM service can choose any unused port number at random. chaotic of them, honestly. 🙈

common firewall configurations block the well-known rpcbind port. in the absence of an rpcbind service, the server administrator fixes the port number of NFS-related services so that the firewall can allow access to specific NFS service ports. client administrators then specify the port number for the mountd service via the mount(8) command's mountport option. it may also be necessary to enforce the use of TCP or UDP if the firewall blocks one of those transports.

💖 NFS Access Control Lists 💖

Solaris allows NFS version 3 clients direct access to POSIX Access Control Lists stored in its local file systems. this proprietary sideband protocol, known as NFSACL, provides richer access control than mode bits. Linux implements this protocol for compatibility with the Solaris NFS implementation. the NFSACL protocol never became a standard part of the NFS version 3 specification, however. so it's giving "popular but never officially crowned." 😭

the NFS version 4 specification mandates a new version of Access Control Lists that are semantically richer than POSIX ACLs. NFS version 4 ACLs are not fully compatible with POSIX ACLs; as such, some translation between the two is required in an environment that mixes POSIX ACLs and NFS version 4. translators stay booked and busy. 🎀

🔁 THE REMOUNT OPTION 🔁

generic mount options such as rw and sync can be modified on NFS mount points using the remount option. see mount(8) for more information on generic mount options.

with few exceptions, NFS-specific options are not able to be modified during a remount. the underlying transport or NFS version cannot be changed by a remount, for example. nope, that ship has sailed. ⛵

performing a remount on an NFS file system mounted with the noac option may have unintended consequences. the noac option is a combination of the generic option sync, and the NFS-specific option actimeo=0. be careful out there bestie. ⚠️

🧚 Unmounting after a remount 🧚

for mount points that use NFS versions 2 or 3, the NFS umount subcommand depends on knowing the original set of mount options used to perform the MNT operation. these options are stored on disk by the NFS mount subcommand, and can be erased by a remount. 😭

to ensure that the saved mount options are not erased during a remount, specify either the local mount directory, or the server hostname and export pathname, but not both, during a remount. for example,

mount -o remount,ro /mnt

merges the mount option ro with the mount options already saved on disk for the NFS server mounted at /mnt. cute, clean, no data loss energy. ✨

📁 FILES 📁

  • /etc/fstab — file system table
  • /etc/nfsmount.conf — Configuration file for NFS mounts

🌸 💅 🌸

📝 NOTES 📝

okay bestie, storytime — here's the kernel lore you need so you don't get caught out. No cap, these are the version limits and quirks:

  • Before 2.4.7, the Linux NFS client did not support NFS over TCP.
  • Before 2.4.20, the Linux NFS client used a heuristic to determine whether cached file data was still valid rather than using the standard close-to-open cache coherency method described above.
  • Starting with 2.4.22, the Linux NFS client employs a Van Jacobsen-based RTT estimator to determine retransmit timeout values when using NFS over UDP.
  • Before 2.6.0, the Linux NFS client did not support NFS version 4.
  • Before 2.6.8, the Linux NFS client used only synchronous reads and writes when the rsize and wsize settings were smaller than the system's page size.
  • The Linux client's support for protocol versions depend on whether the kernel was built with options CONFIG_NFS_V2, CONFIG_NFS_V3, CONFIG_NFS_V4, CONFIG_NFS_V4_1, and CONFIG_NFS_V4_2.

👀 SEE ALSO 👀

bestie, if you wanna go deep, here's the reading list. Receipts, fr fr:

And the RFCs, because citations are iconic:

  • RFC 768 for the UDP specification.
  • RFC 793 for the TCP specification.
  • RFC 1813 for the NFS version 3 specification.
  • RFC 1832 for the XDR specification.
  • RFC 1833 for the RPC bind specification.
  • RFC 2203 for the RPCSEC GSS API protocol specification.
  • RFC 7530 for the NFS version 4.0 specification.
  • RFC 5661 for the NFS version 4.1 specification.
  • RFC 7862 for the NFS version 4.2 specification.

that's a wrap on NFS(5) 💅 — this page is dated 9 October 2012, and the source/version is NFS(5). you're welcome, bestie. now go mount something and slay. 🎀✨

📦 where this page comes from