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

FreeBSD Manual Pages

  
 
  

home | help
unfsd(8)		    System Manager's Manual		      unfsd(8)

NAME
       unfsd - NFS server process

SYNOPSIS
       /usr/sbin/unfsd [options]

DESCRIPTION
       The  unfsd program implements the MOUNT and NFS version 3 protocols. It
       listens for client requests, performs them on the local	filesystem  of
       the  server,  and  then	returns	 the  results of the operations	to the
       clients.

       At startup, unfsd reads the exports file, /etc/exports by  default,  to
       find  out  which	 directories are available to clients and what options
       are in effect (see EXPORTS FILE section below for syntax	 and  possible
       options).

       Normally, unfsd should be run as	the root user. It will then switch its
       effective user and group	id to the numbers listed in incoming  NFS  re-
       quests.	This  means filesystem operations will be performed as if done
       by a local user with the	same ids. If the incoming request is for  user
       or  group  id 0 (meaning	root), unfsd will switch to the	user and group
       id of the nobody	user before performing filesystem operations (this  is
       known  as  root	squashing).   If the user nobody does not exist	on the
       system, a user and group	id of 65534 will be used.  This	 behavior  can
       be  modified by use of the no_root_squash and all_squash	options	in the
       exports file as well as the anonuid and anongid options on a  per-share
       basis.

       If  unfsd is running as a normal	unprivileged user, no switching	of the
       effective user and group	id will	take place.  Instead,  all  filesystem
       operations will be performed with the id	of the user running unfsd.

RESTRICTIONS
       Some  NFS  clients  may attempt to perform operations that unfsd	cannot
       fully support.

       Object Creation
	      When creating filesystem objects,	it is only possible to specify
	      the initial mode for the object. The initial user	and group own-
	      ership, object size, and timestamps cannot be specified and will
	      be set to	default	values.

       File Locking
	      The  network  lock manager (NLM) protocol	is not supported. This
	      means that clients may have to mount with	special	mount options,
	      disabling	 locking  on  the mounted NFS volume (nolock for Linux
	      clients).

OPTIONS
       -h     Display a	short option summary.

       -e _file_
	      Use the given  file  as  the  exports  file,  instead  of	 using
	      /etc/exports.  Note that the file	needs to be specified using an
	      absolute path.

       -i _file_
	      Use the given file as pid	file. When the daemon  starts  up,  it
	      will  write  its	pid (process id) to the	given file. Upon exit,
	      the daemon will remove the file. Failure to create or remove the
	      pid file is not considered fatal and only	reported to syslog.

       -u     Use  an  unprivileged  port for NFS and MOUNT service. Normally,
	      unfsd will use port number 2049, which is	the standard port  for
	      NFS.   When  this	option is in effect, arbitrary ports chosen by
	      the RPC library will be used. You	may need to  use  this	option
	      when running unfsd from a	normal user account.

       -n _port_
	      Use the specified	port for the NFS service.

       -m _port_
	      Use  the specified port for the MOUNT service. The default is to
	      use port number 2049, the	same as	for the	NFS service.  You  can
	      use the same port	for both services if you want.

       -t     TCP  only	 operation. By default,	unfsd provides its services to
	      clients using either UDP or TCP as communications	protocol. When
	      this option is present, only TCP connections are serviced.

       -p     Do  not  register	 with  the portmapper. This will prevent other
	      hosts from finding out the port numbers used for the  MOUNT  and
	      NFS  services  by	querying the portmap daemon. Clients will need
	      to manually specify the port numbers to use (on  Linux  clients,
	      use the mountport	and port mount options).

       -c     Enable  cluster  extensions. This	feature	is only	available when
	      unfsd was	compiled with cluster support. When this option	is en-
	      abled,  so-called	tagged files are handled differently from nor-
	      mal files, making	it possible to serve different	file  contents
	      to  different  clients for the same filename.  See tags(7) for a
	      description of tagged files. This	option	causes	a  performance
	      hit.

       -C _path_
	      Limit the	use of cluster extensions to a list of colon-seperated
	      directories. When	this option is present,	 the  performance  hit
	      caused  by  clustering extensions	only applies to	the listed di-
	      rectories	and their subdirectories.

       -s     Single user mode;	activate basic uid translation.	This option is
	      useful  when  the	server and client are using different user and
	      group ids. All requests from the client will be served from  the
	      user id that started unfsd, no user id switching will take place
	      (even if unfsd was started by root).  Ownership is  reported  as
	      follows:	files belonging	to the user id running unfsd will look
	      as if they are owned by the client's user. Other files will look
	      as  if  they  are	 owned	by root. The same principle applies to
	      group ownership.

       -b     Enable brute force file searching. Normally, when	you  rename  a
	      file across several directories on an NFS	volume,	the filehandle
	      for that file becomes stale. When	this option is enabled,	 unfsd
	      will  attempt a recursive	search on the relevant server filesys-
	      tem to find the file referenced by the filehandle. This can have
	      a	 huge  performance  impact  as this will also happen for files
	      that were	really deleted (by  another  NFS  client)  instead  of
	      moved, and cannot	be found.

       -l <addr>
	      Bind to interface	with specified address.	The default is to bind
	      to all local interfaces.

       -d     Debug mode. When this option is present,	unfsd  will  not  fork
	      into the background at startup, and all messages that would nor-
	      mally go to the system log go to stdout instead.

       -r     Report unreadable	executables as readable. This applies both  to
	      returned	attributes  and	ACCESS requests. Please	note that READ
	      requests for unreadable executables are always allowed, if unfsd
	      is running as root, regardless of	this option.

       -T     Test  exports  file  and	exit. When this	option is given, unfsd
	      will try to parse	the exports file and exit  with	 status	 0  if
	      this  is	successful.  If	there is a syntax error	in the exports
	      file, a message is printed on standard  error  and  unfsd	 exits
	      with status 1.

SIGNALS
       SIGTERM and SIGINT
	      will  cause  unfsd  to unregister	itself from the	portmapper and
	      exit.

       SIGHUP will cause unfsd to re-read its configuration  data.  Currently,
	      this  means  the	program	will query the passwd database to find
	      out the user and group id	of user	nobody.	 unfsd will  also  at-
	      tempt  to	 reload	the exports file. If the exports file contains
	      errors, unfsd sends a warning message  to	 the  system  log  and
	      nothing is exported until	the situation is corrected and another
	      SIGHUP is	sent.

       SIGUSR1
	      will cause unfsd to output statistics about its  filehandle  and
	      file  descriptor	cache  to  the	system log. For	the filehandle
	      cache, it	will output the	number of filehandles  in  the	cache,
	      the  total  number of cache accesses, and	the number of hits and
	      misses. For the file descriptor cache, it	will output the	number
	      of currently held	open READ and WRITE file descriptors.

EXPORTS	FILE
       The exports file, /etc/exports by default, determines which directories
       on the server can be accessed from NFS clients. An example:

       # sample	NFS exports file
       /home		trusted(rw,no_root_squash) (ro)
       "/with spaces"	weirdo
       /usr		1.2.3.4(rw) 192.168.2.0/24(ro,all_squash)
       /home/foo	bar(rw)	10.0.0.0/255.0.0.0(root_squash)
       /home/joe	joes_pc(anonuid=1100,anongid=1100,rw,all_squash)

       Comments	start with a # character and cause the rest of the line	to  be
       ignored.	 Extremely  long exports can be	split across multiple lines by
       escaping	the intermediate newlines with a backslash character.

       Each line starts	with a directory that is to be exported. If the	direc-
       tory name contains whitespace, it must be enclosed in double quotes. To
       the right of the	directory name,	a list of client specifications	can be
       given.  If this list is missing,	the directory is exported to everyone,
       using default options (ro and root_squash).

       If the directory	name contains symbolic links, they are expanded.  This
       means  that  you	 have to force unfsd to	reload the exports file	if the
       symlinks	happen to change.

       Clients can be specified	using either a hostname, an IP address,	or  an
       IP network. Networks can	be given by specifying the number of leading 1
       bits in the netmask or by giving	the full netmask. If the  hostname  is
       empty, the directory is exported	to everyone.

       Options	can  follow  a client specification and	have to	be enclosed in
       parenthesis, with the opening paren directly following the client  name
       or  address. If no options are given, ro	and root_squash	are enabled by
       default.	The following options are supported by unfsd:

       root_squash
	      Enable root squashing, mapping all NFS request done with a  user
	      id  of  0	 to the	user id	of the nobody user. This option	is en-
	      abled by default.

       no_root_squash
	      Disable root squashing. When this	option	is  present,  NFS  re-
	      quests done with a user id of 0 will be done as the root user of
	      the server, effectively disabling	all permissions	checks.

       all_squash
	      Squash all users.	When this option is present, all NFS  requests
	      will be done as the nobody user of the server.

       no_all_squash
	      Don't squash all users. This option is enabled by	default.

       rw     Allow read and write access on the exported directory. When this
	      option is	present, clients are allowed to	modify files  and  di-
	      rectories	on the server.

       ro     Allow  only read access on the exported directory. When this op-
	      tion is present, clients are not allowed to modify files and di-
	      rectories	on the server. This option is enabled by default.

       anonuid/anongid
	      Sets  the	 uid  and gid for anonymous mounts for this share - by
	      default the uid for nobody will be used, but using these options
	      you can change this on a per-share basis.

       secure Allow  only mount	requests coming	from a source port below 1024.
	      Using these ports	requires super-user privileges on many operat-
	      ing systems.  This option	is enabled by default.

       insecure
	      Allow mount requests coming from any source port.

       removable
	      Consider	this  directory	to be on a removable medium. When this
	      option is	present, unfsd will not	keep files open	across	multi-
	      ple read or write	requests. This allows unmounting of the	under-
	      lying filesystem on the server at	any time.   Also,  unfsd  will
	      not  require  that  the exported path exists at startup or mount
	      time. If the path	does not exist,	an  empty  directory  will  be
	      presented	 to  the  client.  This	 is useful for exporting mount
	      points handled by	autofs.

       fixed  Consider this directory to be on a fixed medium. This options is
	      enabled  by  default and allows unfsd to keep files open between
	      multiple read or write requests.

       password=<password>
	      To be able to mount this export, the specified password  is  re-
	      quired.  The password needs be given in the mount	request, as in
	      "mount yourhost:@password:gazonk/tmp /mnt". One  time  passwords
	      are  also	supported. When	using passwords, the file handles will
	      include a	hash of	the password. This means that  if  you	change
	      the password, all	clients	will need to remount this export.  See
	      the file "doc/passwords.txt" in the source for more information.

       If options not present on this list are encountered by unfsd, they  are
       silently	ignored.

BUGS
       There  are  a  few possible race	conditions with	other processes	on the
       server. They can	happen if  unfsd  is  performing  an  operation	 on  a
       filesystem object while another process is simultaneously first (a) re-
       moving the object and then (b) creating a new object of the same	 name.
       If  this	 happens,  unfsd  will attempt to perform the operation	on the
       wrong, new object.  The time window in which this can happen is small.

       When a client does a CREATE EXCLUSIVE procedure call, unfsd stores  the
       verifier	 data  in  the mtime and atime attributes of the created file.
       Malicious processes on the server could	manipulate  those  attributes,
       breaking	the semantics of the exclusive create operation. A process at-
       tempting	to do so would need to be able to see the NFS network traffic.

       unfsd always uses the "nohide" semantics, which means that clients will
       see all file systems mounted below the exported path. However, some NFS
       clients do not cope well	with this situation as,	for  instance,	it  is
       then  possible for two files in the one apparent	filesystem to have the
       same inode number. To avoid this, make sure that	the client mounts each
       exported	file system.

       Due  to the way unfsd operates, it needs	execute	(lookup) and read per-
       mission on all directories from the root	directory all the  way	up  to
       exported	directories.  For example, if /usr/share is exported, unfsd is
       going to	need permission	for  /,	 /usr,	and  /usr/share.   Since  root
       squashing  can  be  in  effect, unfsd may run as	the nobody user, which
       normally	means having to	grant execute (lookup) and read	permission for
       everybody  on  the server.  In the above	example, unfsd also needs per-
       mission to access /usr/share/..,	which can be different from  /usr  for
       some special setups (for	example	when using bind	mounts under Linux).

FILES
       /etc/exports	   Default exports file.

AUTHOR
       Pascal Schmidt

SEE ALSO
       tags(7)

				  05 Jan 2008			      unfsd(8)

NAME | SYNOPSIS | DESCRIPTION | RESTRICTIONS | OPTIONS | SIGNALS | EXPORTS FILE | BUGS | FILES | AUTHOR | SEE ALSO

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

home | help