utils/exportfs/nfsd.man

   1 .\"
   2 .\" nfsd(7) - The nfsd filesystem
   3 .\"
   4 .\" Copyright (C) 2003 Neil Brown <neilb@cse.unsw.edu.au>
   5 .\" Licensed for public use under the terms of the FSF
   6 .\" General Public License (GPL) version 2.
   7 .TH nfsd 7 "3 July 2003"
   8 .SH NAME
   9 nfsd \- special filesystem for controlling Linux NFS server
  10 .SH SYNPOSIS
  11 .B "mount -t nfsd nfsd /proc/fs/nfsd"
  12 .SH DESCRIPTION
  13 The
  14 .B nfsd
  15 filessytem is a special filesystem which provides access to the Linux
  16 NFS server.  The filesystem consists of a single directory which
  17 contains a number of files.  These files are actually gateways into
  18 the NFS server.  Writing to them can affect the server.  Reading from
  19 them can provide information about the server.
  20 .P
  21 This file system is only available in Linux 2.6 and later series
  22 kernels (and in the later parts of the 2.5 development series leading
  23 up to 2.6).  This man page does not apply to 2.4 and earlier.
  24 .P
  25 As well as this filesystem, there are a collection of files in the
  26 .B procfs
  27 filesystem (normally mounted at
  28 .BR /proc )
  29 which are used to control the NFS server.
  30 This manual page describes all of these files.
  31 .P
  32 The
  33 .I exportfs
  34 and
  35 .I mountd
  36 programs (part of the nfs-utils package) expect to find this
  37 filesystem mounted at
  38 .B /proc/fs/nfsd
  39 or
  40 .BR /proc/fs/nfs .
  41 If it is not mounted, they will fall-back on 2.4 style functionality.
  42 This involves accessing the NFS server via a systemcall.  This
  43 systemcall is scheduled to be removed after the 2.6 kernel series.
  44 .SH DETAILS
  45 The three files in the
  46 .B nfsd
  47 filesystem are:
  48 .TP
  49 .B exports
  50 This file contains a list of filesystems that are currently exported
  51 and clients that each filesystem is exported to, together with a list
  52 of export options for that client/filesystem pair.  This is similar
  53 to the
  54 .B /proc/fs/nfs/exports
  55 file in 2.4.
  56 One difference is that a client doesn't necessarily correspond to just
  57 one host.  It can respond to a large collection of hosts that are
  58 being treated identically.
  59
  60 Each line of the file contains a path name, a client name, and a
  61 number of options in parentheses.  Any space, tab, newline or
  62 back-slash character in the path name or client name will be replaced
  63 by a backslash followed by the octal ASCII code for that character.
  64
  65 .TP
  66 .B threads
  67 This file represents the number of
  68 .B nfsd
  69 thread currently running.  Reading it will show the number of
  70 threads.  Writing an ASCII decimal number will cause the number of
  71 threads to be changed (increased or decreased as necessary) to achieve
  72 that number.
  73
  74 .TP
  75 .B filehandle
  76 This is a somewhat unusual file  in that what is read from it depends
  77 on what was just written to it.  It provides a transactional interface
  78 where a program can open the file, write a request, and read a
  79 response.  If two separate programs open, write, and read at the same
  80 time, their requests will not be mixed up.
  81
  82 The request written to
  83 .B filehandle
  84 should be a client name, a path name, and a number of bytes.  This
  85 should be followed by a newline, with white-space separating the
  86 fields, and octal quoting of special characters.
  87
  88 On writing this, the program will be able to read back a filehandle
  89 for that path as exported to the given client.  The filehandles length
  90 will be at most the number of bytes given.
  91
  92 The filehandle will be represented in hex with a leading '\ex'.
  93 .PP
  94 The directory
  95 .B /proc/net/rpc
  96 in the
  97 .B procfs
  98 filesystem contains a number of files and directories.
  99 The files contain statistics that can be display using the
 100 .I nfsstat
 101 program.
 102 The directories contain information about various caches that the NFS
 103 server maintains to keep track of access permissions that different
 104 clients have for different filesystems.
 105 The caches are:
 106
 107 .TP
 108 .B auth.domain
 109 This cache maps the name of a client (or domain) to an internal data
 110 structure.  The only access that is possible is to flush the cache.
 111
 112 .TP
 113 .B auth.unix.ip
 114 This cache contains a mapping from IP address to the name of the
 115 authentication domain that the ipaddress should be treated as part of.
 116
 117 .TP
 118 .B nfsd.export
 119 This cache contains a mapping from directory and domain to export
 120 options.
 121
 122 .TP
 123 .B nfsd.fh
 124 This cache contains a mapping from domain and a filesystem identifier
 125 to a directory.   The filesystem identifier is stored in the
 126 filehandles and consists of a number indicating the type of identifier
 127 and a number of hex bytes indicating the content of the identifier.
 128
 129 .PP
 130 Each directory representing a cache can hold from 1 to 3 files.  They
 131 are:
 132 .TP
 133 .B flush
 134 When a number of seconds since epoch (1 Jan 1970) is written to this
 135 file, all entries in the cache that were last updated before that file
 136 become invalidated and will be flushed out.  Writing 1 will flush
 137 everything.  This is the only file that will always be present.
 138
 139 .TP
 140 .B content
 141 This file, if present, contains a textual representation of ever entry
 142 in the cache, one per line.  If an entry is still in the cache
 143 (because it is actively being used) but has expired or is otherwise
 144 invalid, it will be presented as a comment (with a leading hash
 145 character).
 146
 147 .TP
 148 .B channel
 149 This file, if present, acts a channel for request from the kernel-based
 150 nfs server to be passed to a user-space program for handling.
 151
 152 When the kernel needs some information which isn't in the cache, it
 153 makes a line appear in the
 154 .B channel
 155 file giving the key for the information.  A user-space program should
 156 read this, find the answer, and write a line containing the key, an
 157 expiry time, and the content.
 158 For example the kernel might make
 159 .ti +5
 160 nfsd 127.0.0.1
 161 .br
 162 appear in the
 163 .B auth.unix.ip/content
 164 file.  The user-space program might then write
 165 .ti +5
 166 nfsd 127.0.0.1 1057206953 localhost
 167 .br
 168 to indicate that 127.0.0.1 should map to localhost, atleast for now.
 169
 170 If the program uses select(2) or poll(2) to discover if it can read
 171 from the
 172 .B channel
 173 then it will never see and end-of-file but when all requests have been
 174 answered, it will block until another request appears.
 175
 176 .PP
 177 In the
 178 .B /proc
 179 filesystem there are 4 files that can be used to enabled extra tracing
 180 of nfsd and related code.  They are:
 181 .in +5
 182 .B /proc/sys/sunrpc/nfs_debug
 183 .br
 184 .B /proc/sys/sunrpc/nfsd_debug
 185 .br
 186 .B /proc/sys/sunrpc/nlm_debug
 187 .br
 188 .B /proc/sys/sunrpc/rpc_debug
 189 .br
 190 .in -5
 191 They control tracing for the NFS client, the NFS server, the Network
 192 Lock Manager (lockd) and the underlying RPC layer respectively.
 193 Decimal numbers can be read from or written to these files.  Each
 194 number represents a bit-pattern where bits that are set cause certain
 195 classes of tracing to be enabled.  Consult the kernel header files to
 196 find out what number correspond to what tracing.
 197
 198 .SH SEE ALSO
 199 .BR rpc.nfsd (8),
 200 .BR exports (5),
 201 .BR nfsstat (8),
 202 .BR mountd (8)
 203 .BR exportfs (8).
 204
 205 .SH AUTHOR
 206 NeilBrown