1.\" Copyright (c) 2009 Rick Macklem, University of Guelph 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd April 30, 2009 28.Dt NFSV4 4 29.Os 30.Sh NAME 31.Nm nfsv4 32.Nd NFS Version 4 Protocol 33.Sh SYNOPSIS 34experimental client and server with NFSv4 support 35.Sh DESCRIPTION 36The experimental nfs client and server provides support for the 37.Tn NFSv4 38specification; see 39.%T "Network File System (NFS) Version 4 Protocol \\*(tNRFC\\*(sP 3530" . 40The protocol is somewhat similar to NFS Version 3, but differs in significant 41ways. It uses a single Compound RPC that concatenates operations to-gether. 42Each of these operations are similar to the RPCs of NFS Version 3. 43The operations in the compound are performed in order, until one of 44them fails (returns an error) and then the RPC terminates at that point. 45.Pp 46It has 47integrated locking support, which implies that the server is no longer 48stateless. As such, the 49.Tn NFSv4 50server remains in recovery mode for a Grace period (always greater than the 51lease duration the server uses) after a reboot. 52During this Grace period, clients may recover state but not perform other 53open/lock state changing operations. 54To provide for correct recovery semantics, a small file described by 55.Xr stablerestart 5 56is used by the server during the recovery phase. If this file is missing, 57the server will not start. 58If this file is lost, it should be recovered from backups, since creating 59an empty 60.Xr stablerestart 5 61file will result in the server starting without providing a Grace Period 62for recovery. 63Note that recovery only occurs when the server 64machine is rebooted, not when the 65.Xr nfsd 8 66are just restarted. 67.Pp 68It provides several optional features not in NFS Version 3: 69.sp 70.Bd -literal -offset indent -compact 71- NFS Version 4 ACLs 72- Referrals, which redirect subtrees to other servers 73 (not yet implemented) 74- Delegations, which allow a client to operate on a file locally 75.Ed 76.Pp 77The 78.Tn NFSv4 79protocol does not use a separate mount protocol and assumes that the 80server provides a single file system tree structure, rooted at the point 81in the local file system tree specified by the 82.sp 1 83.Bd -literal -offset indent -compact 84V4: <rootdir> 85.Ed 86.sp 1 87line in 88.Xr exports 5 . 89The 90.Xr nfsd 8 91allows a limited subset of operations to be performed on non-exported subtrees 92of the local file system, so that traversal of the tree to the exported 93subtrees is possible. 94As such, the ``<rootdir>'' can be in a non-exported file system. However, 95the entire tree that is rooted at that point must be in local file systems 96that are of types that can be NFS exported. 97Since the 98.Nm 99file system is rooted at ``<rootdir>'', setting this to anything other 100than ``/'' will result in clients being required to use different mount 101paths for 102.Nm 103than for NFS Version 2 or 3. 104Unlike NFS Version 2 and 3, Version 4 allows a client mount to span across 105multiple server file systems, although not all clients are capable of doing 106this. 107.Pp 108.Nm 109uses names for users and groups instead of numbers. On the wire, they 110take the form: 111.sp 112.Bd -literal -offset indent -compact 113<user>@<dns.domain> 114.Ed 115.sp 116where ``<dns.domain>'' is not the same as the DNS domain used 117for host name lookups, but is usually set to the same string. Most systems set this ``<dns.domain>'' 118to the domain name part of the machine's 119.Xr hostname 1 120by default. However, this can normally be overridden by a command line 121option or configuration file for the daemon used to do the name<->number 122mapping. 123On FreeBSD, the mapping daemon is called 124.Xr nfsuserd 8 125and has a command line option that overrides the domain component of the 126machine's hostname. 127This can be set in 128.Xr rc.conf 5 129via the nfsv4_userd_flags variable. 130For use of 131.Nm , 132either client or server, this daemon must be enabled by setting 133.sp 134.Bd -literal -offset indent -compact 135nfsv4_enable="YES" 136.Ed 137.sp 138in 139.Xr rc.conf 5 . 140If this ``<dns.domain>'' is not set correctly or the daemon is not running, ``ls -l'' will typically 141report a lot of ``nobody'' and ``nogroup'' ownerships. 142.Pp 143Although numbers are no longer used in the 144.Nm 145protocol, they will still be in the RPC authentication fields when running 146using AUTH_SYS (sec=sys), which is the default. 147As such, in this case both the user/group name and number spaces must 148be consistent between the client and server. 149.Pp 150However, if you run 151.Nm 152with RPCSEC_GSS (sec=krb5, krb5i, krb5p), only names and KerberosV tickets 153will go on the wire. 154.Sh SERVER SETUP 155.Pp 156To set up the experimental nfs server that supports 157.Nm 158you will need to either build a kernel with: 159.sp 160.Bd -literal -offset indent -compact 161options NFSD 162.Ed 163and not 164.Bd -literal -offset indent -compact 165options NFSSERVER 166.Ed 167.sp 168or start 169.Xr mountd 8 170and 171.Xr nfsd 8 172with the ``-4'' option to force use of the experimental server. 173This will occur if 174.sp 175.Bd -literal -offset indent -compact 176nfsv4_enable="YES" 177.Ed 178.sp 179is set in 180.Xr rc.conf 5 , 181as above. 182.Pp 183You will also need to add a: 184.sp 185.Bd -literal -offset indent -compact 186V4: <rootdir> 187.Ed 188.sp 189line to the 190.Xr exports 5 191file, to tell the server where the 192.Nm 193tree is rooted. 194.Pp 195If the file systems you are exporting are only being accessed via 196.Nm 197there are a couple of 198.Xr sysctl 8 199variables that you can change, which might improve performance. 200.Bl -tag -width Ds 201.It Cm vfs.newnfs.issue_delegations 202when set non-zero, allows the server to issue Open Delegations to 203clients. These delegations permit the client to manipulate the file 204locally on the client. Unfortunately, at this time, client use of 205delegations is limited, so performance gains may not be observed. 206This can only be enabled when the file systems being exported to 207.Nm 208clients are not being accessed locally on the server and, if being 209accessed via NFS Version 2 or 3 clients, these clients cannot be 210using the NLM. 211.It Cm vfs.newnfs.enable_locallocks 212can be set to 0 to disable acquisition of local byte range locks. 213Disabling local locking can only be done if neither local accesses 214to the exported file systems nor the NLM is operating on them. 215.El 216.sp 217Note that Samba server access would be considered ``local access'' for the above 218discussion. 219.Pp 220To build a kernel with the experimental 221.Nm 222linked into it, the 223.sp 224.Bd -literal -offset indent -compact 225options NFSD 226.Ed 227.sp 228must be specified in the kernel's 229.Xr config 5 230file. 231.Sh CLIENT MOUNTS 232.Pp 233To do an 234.Nm 235mount, specify the ``nfsv4'' option on the 236.Xr mount_nfs 8 237command line. 238This will force use of the experimental client plus set ``tcp'' and 239.Nm . 240.Pp 241If the 242.Nm 243server that is being mounted on supports delegations, you can set 244.sp 245.Bd -literal -offset indent -compact 246nfsv4_callbackdaemon_enable="YES" 247.Ed 248.sp 249via 250.Xr rc.conf 5 251so that the client side callback daemon 252.Xr nfscbd 8 253is started upon boot. 254Without a functioning callback path, a server will never issue Delegations 255to a client. 256.sp 257By default, the callback address will be set to the IP address acquired via 258rtalloc() in the kernel and port# 7745. 259To override the default port#, a command line option for 260.Xr nfscbd 8 261can be set via the variable 262.sp 263.Bd -literal -offset indent -compact 264nfsv4_callbackdaemon_flag 265.Ed 266.sp 267using 268.Xr rc.conf 5 . 269.sp 270To get callbacks to work when behind a NAT gateway, a port for the callback 271service will need to be set up on the NAT gateway and then the address 272of the NAT gateway (host IP plus port#) will need to be set by assigning the 273.Xr sysctl 8 274variable vfs.newnfs.callback_addr to a string of the form: 275.sp 276N.N.N.N.N.N 277.sp 278where the first 4 Ns are the host IP address and the last two are the 279port# in network byte order (all decimal #s in the range 0-255). 280.Pp 281To build a kernel with the experimental 282.Nm 283client linked into it, the option 284.sp 285.Bd -literal -offset indent -compact 286options NFSCL 287.Ed 288.sp 289must be specified in the kernel's 290.Xr config 5 291file. 292.Sh FILES 293.Bl -tag -width /var/db/nfs-stablerestart -compact 294.It Pa /var/db/nfs-stablerestart 295NFS V4 stable restart file 296.El 297.Sh SEE ALSO 298.Xr stablerestart 5 299.Xr mountd 8 300.Xr nfscbd 8 301.Xr nfsd 8 302.Xr nfsdumpstate 8 303.Xr nfsrevoke 8 304.Xr nfsuserd 8 305.Sh BUGS 306At this time, there is no recall of delegations for local file system 307operations. As such, delegations should only be enabled for file systems 308that are being used soley as NFS export volumes and are not being accessed 309via local system calls nor services such as Samba. 310