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