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