Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NFSV4(4)		    Kernel Interfaces Manual		      NFSV4(4)

NAME
       nfsv4 --	NFS Version 4 Protocol

SYNOPSIS
       experimental client and server with NFSv4 support

DESCRIPTION
       The  experimental  nfs client and server	provides support for the NFSv4
       specification; see Network File System (NFS)  Version  4	 Protocol  RFC
       3530.   The  protocol is	somewhat similar to NFS	Version	3, but differs
       in significant ways.  It	uses a single Compound RPC  that  concatenates
       operations to-gether.  Each of these operations are similar to the RPCs
       of  NFS Version 3.  The operations in the compound are performed	in or-
       der, until one of them fails (returns an	error) and then	the RPC	termi-
       nates at	that point.

       It has integrated locking support, which	implies	that the server	is  no
       longer  stateless.   As such, the NFSv4 server remains in recovery mode
       for a Grace period (always greater than the lease duration  the	server
       uses)  after  a	reboot.	 During	this Grace period, clients may recover
       state but not perform other open/lock state  changing  operations.   To
       provide	for  correct  recovery	semantics,  a  small file described by
       stablerestart(5)	is used	by the server during the recovery  phase.   If
       this file is missing, the server	will not start.	 If this file is lost,
       it   should   be	 recovered  from  backups,  since  creating  an	 empty
       stablerestart(5)	file will result in the	server starting	 without  pro-
       viding  a  Grace	 Period	 for recovery.	Note that recovery only	occurs
       when the	server machine is rebooted, not	 when  the  nfsd(8)  are  just
       restarted.

       It provides several optional features not in NFS	Version	3:

	     - NFS Version 4 ACLs
	     - Referrals, which	redirect subtrees to other servers
	       (not yet	implemented)
	     - Delegations, which allow	a client to operate on a file locally

       The  NFSv4  protocol does not use a separate mount protocol and assumes
       that the	server provides	a single file system tree structure, rooted at
       the point in the	local file system tree specified by one	or more

	     V4: <rootdir> [-sec=secflavors] [host(s) or net]

       line(s) in the exports(5) file.	(See  exports(5)  for  details.)   The
       nfsd(8)	allows	a limited subset of operations to be performed on non-
       exported	subtrees of the	local file system, so that  traversal  of  the
       tree  to	the exported subtrees is possible.  As such, the ``<rootdir>''
       can be in a non-exported	file system.  However, the entire tree that is
       rooted at that point must be in local file systems that	are  of	 types
       that  can  be  NFS  exported.  Since the	nfsv4 file system is rooted at
       ``<rootdir>'', setting this to anything other than ``/''	will result in
       clients being required to use different mount paths for nfsv4 than  for
       NFS  Version  2	or  3.	Unlike NFS Version 2 and 3, Version 4 allows a
       client mount to span across multiple server file	systems, although  not
       all clients are capable of doing	this.

       nfsv4 uses names	for users and groups instead of	numbers.  On the wire,
       they take the form:

	     <user>@<dns.domain>

       where  ``<dns.domain>'' is not the same as the DNS domain used for host
       name lookups, but is usually set	to the same string.  Most systems  set
       this  ``<dns.domain>''  to  the	domain	name  part  of	the  machine's
       hostname(1) by default.	However, this can normally be overridden by  a
       command line option or configuration file for the daemon	used to	do the
       name<->number  mapping.	 On  FreeBSD,  the  mapping  daemon  is	called
       nfsuserd(8) and has a command line option  that	overrides  the	domain
       component  of  the machine's hostname.  For use of nfsv4, either	client
       or server, this daemon must be running.	If  this  ``<dns.domain>''  is
       not  set	 correctly  or the daemon is not running, ``ls -l'' will typi-
       cally report a lot of ``nobody''	and ``nogroup''	ownerships.

       Although	uid/gid	numbers	are no longer used in the nfsv4	protocol, they
       will still be in	the  RPC  authentication  fields  when	running	 using
       AUTH_SYS	 (sec=sys),  which is the default.  As such, in	this case both
       the user/group name and number spaces must be  consistent  between  the
       client and server.

       However,	 if  you  run  nfsv4 with RPCSEC_GSS (sec=krb5,	krb5i, krb5p),
       only names and KerberosV	tickets	will go	on the wire.

SERVER SETUP
       To set up the experimental nfs server that supports nfsv4 you will need
       to either build a kernel	with:

	     options NFSD
       and not
	     options NFSSERVER

       or start	mountd(8) and nfsd(8) with the ``-e'' option to	force  use  of
       the  experimental server.  The nfsuserd(8) daemon must also be running.
       This will occur if

	     nfs_server_enable="YES"
	     nfsv4_server_enable="YES"
	     nfsuserd_enable="YES"

       are set in rc.conf(5).

       You will	also need to add at least one ``V4:'' line to  the  exports(5)
       file  and,  before  starting  the  server for the first time, create an
       empty

	     /var/db/nfs-stablerestart

       file.  The command

	     install -o	root -g	wheel -m 600 /dev/null /var/db/nfs-stablerestart

       executed	as ``su'' should suffice.  This	can  only  be  done  when  the
       server is not running and there are no nfsv4 file system	mounts against
       the server.  If this file is lost during	a crash, recovery from backups
       is recommended.

       If the file systems you are exporting are only being accessed via nfsv4
       there  are  a  couple of	sysctl(8) variables that you can change, which
       might improve performance.

       vfs.newnfs.issue_delegations
	       when set	non-zero, allows the server to issue Open  Delegations
	       to  clients.  These delegations permit the client to manipulate
	       the file	locally	on the client.	Unfortunately, at  this	 time,
	       client  use of delegations is limited, so performance gains may
	       not be observed.	 This can only be enabled when the  file  sys-
	       tems being exported to nfsv4 clients are	not being accessed lo-
	       cally on	the server and,	if being accessed via NFS Version 2 or
	       3 clients, these	clients	cannot be using	the NLM.

       vfs.newnfs.enable_locallocks
	       can  be	set  to	 0  to disable acquisition of local byte range
	       locks.  Disabling local locking can only	be done	if neither lo-
	       cal accesses to the exported file systems nor the NLM is	 oper-
	       ating on	them.

       Note  that Samba	server access would be considered ``local access'' for
       the above discussion.

       To build	a kernel with the experimental nfsv4 linked into it, the

	     options NFSD

       must be specified in the	kernel's config(5) file.

CLIENT MOUNTS
       To do an	nfsv4 mount, specify the ``nfsv4'' option on the  mount_nfs(8)
       command	line.  This will force use of the experimental client plus set
       ``tcp'' and nfsv4.

       The nfsuserd(8) must be running,	as above.  If the nfsv4	server that is
       being mounted on	supports delegations, you can start the	nfscbd(8) dae-
       mon to handle client side callbacks.  This will occur if

	     nfsuserd_enable="YES"
	     nfscbd_enable="YES"

       are set in rc.conf(5).

       Without a functioning callback path, a server will never	issue  Delega-
       tions to	a client.

       By default, the callback	address	will be	set to the IP address acquired
       via  rtalloc()  in  the kernel and port#	7745.  To override the default
       port#, a	command	line option for	nfscbd(8) can be used.

       To get callbacks	to work	when behind a NAT  gateway,  a	port  for  the
       callback	service	will need to be	set up on the NAT gateway and then the
       address	of the NAT gateway (host IP plus port#)	will need to be	set by
       assigning the sysctl(8) variable	vfs.newnfs.callback_addr to  a	string
       of the form:

       N.N.N.N.N.N

       where  the  first 4 Ns are the host IP address and the last two are the
       port# in	network	byte order (all	decimal	#s in the range	0-255).

       To build	a kernel with the experimental nfsv4 client  linked  into  it,
       the option

	     options NFSCL

       must be specified in the	kernel's config(5) file.

       Options	can  be	specified for the nfsuserd(8) and nfscbd(8) daemons at
       boot time via the ``nfsuserd_flags''  and  ``nfscbd_flags''  rc.conf(5)
       variables.

FILES
       /var/db/nfs-stablerestart  NFS V4 stable	restart	file

SEE ALSO
       stablerestart(5)	   mountd(8)	nfscbd(8)    nfsd(8)   nfsdumpstate(8)
       nfsrevoke(8) nfsuserd(8)

BUGS
       At this time, there is no recall	of delegations for local  file	system
       operations.   As	such, delegations should only be enabled for file sys-
       tems that are being used	soley as NFS export volumes and	are not	 being
       accessed	via local system calls nor services such as Samba.

GNU				April 30, 2009			      NFSV4(4)

NAME | SYNOPSIS | DESCRIPTION | SERVER SETUP | CLIENT MOUNTS | FILES | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nfsv4&manpath=FreeBSD+8.1-RELEASE+and+Ports>

home | help