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 December 3, 2009 28.Dt NFSV4 4 29.Os 30.Sh NAME 31.Nm NFSv4 32.Nd NFS Version 4 Protocol 33.Sh DESCRIPTION 34The experimental NFS client and server provides support for the 35.Tn NFSv4 36specification; see 37.%T "Network File System (NFS) Version 4 Protocol RFC 3530" . 38The protocol is somewhat similar to NFS Version 3, but differs in significant 39ways. 40It uses a single compound RPC that concatenates operations to-gether. 41Each of these operations are similar to the RPCs of NFS Version 3. 42The operations in the compound are performed in order, until one of 43them fails (returns an error) and then the RPC terminates at that point. 44.Pp 45It has 46integrated locking support, which implies that the server is no longer 47stateless. 48As such, the 49.Nm 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. 57If this file is missing, 58the server will not start. 59If this file is lost, it should be recovered from backups, since creating 60an empty 61.Xr stablerestart 5 62file will result in the server starting without providing a grace period 63for recovery. 64Note that recovery only occurs when the server 65machine is rebooted, not when the 66.Xr nfsd 8 67are just restarted. 68.Pp 69It provides several optional features not present in NFS Version 3: 70.sp 71.Bd -literal -offset indent -compact 72- NFS Version 4 ACLs 73- Referrals, which redirect subtrees to other servers 74 (not yet implemented) 75- Delegations, which allow a client to operate on a file locally 76.Ed 77.Pp 78The 79.Nm 80protocol does not use a separate mount protocol and assumes that the 81server provides a single file system tree structure, rooted at the point 82in the local file system tree specified by one or more 83.sp 1 84.Bd -literal -offset indent -compact 85V4: <rootdir> [-sec=secflavors] [host(s) or net] 86.Ed 87.sp 1 88line(s) in the 89.Xr exports 5 90file. 91(See 92.Xr exports 5 93for details.) 94The 95.Xr nfsd 8 96allows a limited subset of operations to be performed on non-exported subtrees 97of the local file system, so that traversal of the tree to the exported 98subtrees is possible. 99As such, the ``<rootdir>'' can be in a non-exported file system. 100However, 101the entire tree that is rooted at that point must be in local file systems 102that are of types that can be NFS exported. 103Since the 104.Nm 105file system is rooted at ``<rootdir>'', setting this to anything other 106than ``/'' will result in clients being required to use different mount 107paths for 108.Nm 109than for NFS Version 2 or 3. 110Unlike NFS Version 2 and 3, Version 4 allows a client mount to span across 111multiple server file systems, although not all clients are capable of doing 112this. 113.Pp 114.Nm 115uses names for users and groups instead of numbers. 116On the wire, they 117take the form: 118.sp 119.Bd -literal -offset indent -compact 120<user>@<dns.domain> 121.Ed 122.sp 123where ``<dns.domain>'' is not the same as the DNS domain used 124for host name lookups, but is usually set to the same string. 125Most systems set this ``<dns.domain>'' 126to the domain name part of the machine's 127.Xr hostname 1 128by default. 129However, this can normally be overridden by a command line 130option or configuration file for the daemon used to do the name<->number 131mapping. 132Under FreeBSD, the mapping daemon is called 133.Xr nfsuserd 8 134and has a command line option that overrides the domain component of the 135machine's hostname. 136For use of 137.Nm , 138either client or server, this daemon must be running. 139If this ``<dns.domain>'' is not set correctly or the daemon is not running, ``ls -l'' will typically 140report a lot of ``nobody'' and ``nogroup'' ownerships. 141.Pp 142Although uid/gid numbers are no longer used in the 143.Nm 144protocol, they will still be in the RPC authentication fields when 145using AUTH_SYS (sec=sys), which is the default. 146As such, in this case both the user/group name and number spaces must 147be consistent between the client and server. 148.Pp 149However, if you run 150.Nm 151with RPCSEC_GSS (sec=krb5, krb5i, krb5p), only names and KerberosV tickets 152will go on the wire. 153.Sh SERVER SETUP 154.Pp 155To set up the experimental NFS server that supports 156.Nm , 157you will need to either build a kernel with: 158.sp 159.Bd -literal -offset indent -compact 160options NFSD 161.Ed 162and not 163.Bd -literal -offset indent -compact 164options NFSSERVER 165.Ed 166.sp 167or start 168.Xr mountd 8 169and 170.Xr nfsd 8 171with the ``-e'' option to force use of the experimental server. 172The 173.Xr nfsuserd 8 174daemon must also be running. 175This will occur if 176.sp 177.Bd -literal -offset indent -compact 178nfs_server_enable="YES" 179nfsv4_server_enable="YES" 180nfsuserd_enable="YES" 181.Ed 182.sp 183are set in 184.Xr rc.conf 5 . 185.Pp 186You will also need to add at least one ``V4:'' line to the 187.Xr exports 5 188file and, before starting the server for the first time, create an empty 189.sp 190.Bd -literal -offset indent -compact 191/var/db/nfs-stablerestart 192.Ed 193.sp 194file. 195The command 196.sp 197.Bd -literal -offset indent -compact 198install -o root -g wheel -m 600 /dev/null /var/db/nfs-stablerestart 199.Ed 200.sp 201executed as ``su'' should suffice. 202This can only be done when the server is not running and there are no 203.Nm 204file system mounts against the server. 205If this file is lost during a crash, recovery from backups is 206recommended. 207.Pp 208If the file systems you are exporting are only being accessed via 209.Nm 210there are a couple of 211.Xr sysctl 8 212variables that you can change, which might improve performance. 213.Bl -tag -width Ds 214.It Cm vfs.newnfs.issue_delegations 215when set non-zero, allows the server to issue Open Delegations to 216clients. 217These delegations permit the client to manipulate the file 218locally on the client. 219Unfortunately, at this time, client use of 220delegations is limited, so performance gains may not be observed. 221This can only be enabled when the file systems being exported to 222.Nm 223clients are not being accessed locally on the server and, if being 224accessed via NFS Version 2 or 3 clients, these clients cannot be 225using the NLM. 226.It Cm vfs.newnfs.enable_locallocks 227can be set to 0 to disable acquisition of local byte range locks. 228Disabling local locking can only be done if neither local accesses 229to the exported file systems nor the NLM is operating on them. 230.El 231.sp 232Note that Samba server access would be considered ``local access'' for the above 233discussion. 234.Pp 235To build a kernel with the experimental 236.Nm 237linked into it, the 238.sp 239.Bd -literal -offset indent -compact 240options NFSD 241.Ed 242.sp 243must be specified in the kernel's 244.Xr config 5 245file. 246.Sh CLIENT MOUNTS 247.Pp 248To do an 249.Nm 250mount, specify the ``nfsv4'' option on the 251.Xr mount_nfs 8 252command line. 253This will force use of the experimental client plus set ``tcp'' and 254.Nm . 255.Pp 256The 257.Xr nfsuserd 8 258must be running, as above. 259If the 260.Nm 261server that is being mounted on supports delegations, you can start the 262.Xr nfscbd 8 263daemon to handle client side callbacks. 264This will occur if 265.sp 266.Bd -literal -offset indent -compact 267nfsuserd_enable="YES" 268nfscbd_enable="YES" 269.Ed 270.sp 271are set in 272.Xr rc.conf 5 . 273.sp 274Without a functioning callback path, a server will never issue Delegations 275to a client. 276.sp 277By default, the callback address will be set to the IP address acquired via 278rtalloc() in the kernel and port# 7745. 279To override the default port#, a command line option for 280.Xr nfscbd 8 281can be used. 282.sp 283To get callbacks to work when behind a NAT gateway, a port for the callback 284service will need to be set up on the NAT gateway and then the address 285of the NAT gateway (host IP plus port#) will need to be set by assigning the 286.Xr sysctl 8 287variable vfs.newnfs.callback_addr to a string of the form: 288.sp 289N.N.N.N.N.N 290.sp 291where the first 4 Ns are the host IP address and the last two are the 292port# in network byte order (all decimal #s in the range 0-255). 293.Pp 294To build a kernel with the experimental 295.Nm 296client linked into it, the option 297.sp 298.Bd -literal -offset indent -compact 299options NFSCL 300.Ed 301.sp 302must be specified in the kernel's 303.Xr config 5 304file. 305.Pp 306Options can be specified for the 307.Xr nfsuserd 8 308and 309.Xr nfscbd 8 310daemons at boot time via the ``nfsuserd_flags'' and ``nfscbd_flags'' 311.Xr rc.conf 5 312variables. 313.Sh FILES 314.Bl -tag -width /var/db/nfs-stablerestart -compact 315.It Pa /var/db/nfs-stablerestart 316NFS V4 stable restart file 317.El 318.Sh SEE ALSO 319.Xr stablerestart 5 , 320.Xr mountd 8 , 321.Xr nfscbd 8 , 322.Xr nfsd 8 , 323.Xr nfsdumpstate 8 , 324.Xr nfsrevoke 8 , 325.Xr nfsuserd 8 , 326.Sh BUGS 327At this time, there is no recall of delegations for local file system 328operations. 329As such, delegations should only be enabled for file systems 330that are being used soley as NFS export volumes and are not being accessed 331via local system calls nor services such as Samba. 332