new man page - nfsd.7
authorneilbrown <neilbrown>
Thu, 3 Jul 2003 06:14:10 +0000 (06:14 +0000)
committerneilbrown <neilbrown>
Thu, 3 Jul 2003 06:14:10 +0000 (06:14 +0000)
ChangeLog
config.mk.in
rules.mk
utils/exportfs/Makefile
utils/exportfs/nfsd.man [new file with mode: 0644]
utils/nfsd/Makefile

index 463a301..6eda83a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
+       
 2003-07-03 NeilBrown <neilb@cse.unsw.edu.au>
 
+       * utils/exportfs/nfsd.man: new man page for nfsd filesystem. Also
+       assorted changed to cope with section 7 of the manual.
        * configure.in, nfs-utils.spec: Update version to 1.0.4
        * run autoconf
 
index 18d4f39..d2cbea0 100644 (file)
@@ -22,6 +22,7 @@ NFSV3         = @enable_nfsv3@
 # Where and how to install manpages
 MAN1EXT                = 1
 MAN5EXT                = 5
+MAN7EXT                = 7
 MAN8EXT                = 8
 MAN9EXT                = 9
 MANOWNER       = root
@@ -87,5 +88,6 @@ INSTALLMOD    = $(INSTALL) -m 600
 INSTALLMAN     = $(INSTALL) -m 644
 MAN1DIR                = $(MANDIR)/man$(MAN1EXT)
 MAN5DIR                = $(MANDIR)/man$(MAN5EXT)
+MAN7DIR                = $(MANDIR)/man$(MAN7EXT)
 MAN8DIR                = $(MANDIR)/man$(MAN8EXT)
 MAN9DIR                = $(MANDIR)/man$(MAN9EXT)
index 6796f19..27b81bc 100644 (file)
--- a/rules.mk
+++ b/rules.mk
@@ -81,22 +81,22 @@ distclean::
 ##################################################################
 ifneq ($(MAN1)$(MAN5)$(MAN8)$(MAN9),)
 MANINIT        = ext=$(MAN$sEXT); dir=$(MAN$sDIR); pgs="$(MAN$s)";
-MANLOOP = $(MANINIT) for man in $$pgs; do eval $$cmd; done
+MANLOOP = $(MANINIT) for man in $$pgs; do mn=`echo $$man | sed 's/[0-9]$$//'`; eval $$cmd; done
 MDCMD  = $(MKDIR) \$$dir
-MICMD  = $(RM) \$$dir/\$$man.\$$ext; \
-         echo $(INSTALLMAN) \$$man.man \$$dir/\$$man.\$$ext; \
-         $(INSTALLMAN) \$$man.man \$$dir/\$$man.\$$ext
-LNCMD  = $(RM) \$$dir/$(PREFIX)\$$man.\$$ext; \
-         echo $(LN_S) \$$man.\$$ext \$$dir/$(PREFIX)\$$man.\$$ext; \
-         $(LN_S) \$$man.\$$ext \$$dir/$(PREFIX)\$$man.\$$ext
+MICMD  = $(RM) \$$dir/\$$mn.\$$ext; \
+         echo $(INSTALLMAN) \$$man.man \$$dir/\$$mn.\$$ext; \
+         $(INSTALLMAN) \$$man.man \$$dir/\$$mn.\$$ext
+LNCMD  = $(RM) \$$dir/$(PREFIX)\$$mn.\$$ext; \
+         echo $(LN_S) \$$mn.\$$ext \$$dir/$(PREFIX)\$$mn.\$$ext; \
+         $(LN_S) \$$mn.\$$ext \$$dir/$(PREFIX)\$$mn.\$$ext
 PSCMD  = echo \"$(MAN2PS) \$$man.man > $(TOP)postscript/\$$man.ps\"; \
          $(MAN2PS) \$$man.man > $(TOP)postscript/\$$man.ps
 
 installman::
-       @$(foreach s, 1 5 8 9, cmd="$(MDCMD)" $(MANLOOP);)
-       @$(foreach s, 1 5 8 9, cmd="$(MICMD)" $(MANLOOP);)
+       @$(foreach s, 1 5 8 9, cmd="$(MDCMD)" $(MANLOOP);)
+       @$(foreach s, 1 5 8 9, cmd="$(MICMD)" $(MANLOOP);)
 ifneq ($(PREFIX),)
-       @$(foreach s, 1 5 8 9, cmd="$(LNCMD)" $(MANLOOP);)
+       @$(foreach s, 1 5 8 9, cmd="$(LNCMD)" $(MANLOOP);)
 endif
 
 postscript::
@@ -113,7 +113,7 @@ ifneq ($(SRCS),)
 indent:
        $(INDENT) $(SRCS)
 endif
-       
+
 ##################################################################
 # Handling of dependencies
 ##################################################################
index 8cd7029..aa77540 100644 (file)
@@ -8,6 +8,7 @@ LIBDEPS = $(TOP)support/lib/libexport.a $(TOP)/support/lib/libnfs.a
 LIBS   = -lexport -lnfs -lmisc
 MAN8   = exportfs
 MAN5   = exports
+MAN7   = nfsd
 
 include $(TOP)rules.mk
 
diff --git a/utils/exportfs/nfsd.man b/utils/exportfs/nfsd.man
new file mode 100644 (file)
index 0000000..b4806b4
--- /dev/null
@@ -0,0 +1,204 @@
+.\"
+.\" nfsd(7) - The nfsd filesystem
+.\"
+.\" Copyright (C) 2003 Neil Brown <neilb@cse.unsw.edu.au>
+.\" Licensed for public use under the terms of the FSF
+.\" General Public License (GPL) version 2.
+.TH nfsd 7 "3 July 2003"
+.SH NAME
+nfsd \- special filesystem for controlling Linux NFS server
+.SH SYNPOSIS
+.B "mount -t nfsd nfsd /proc/fs/nfs"
+.SH DESCRIPTION
+The
+.B nfsd
+filessytem is a special filesystem which provides access to the Linux
+NFS server.  The filesystem consists of a single directory which
+contains a number of files.  These files are actually gateways into
+the NFS server.  Writing to them can affect the server.  Reading from
+them can provide information about the server.
+.P
+This file system is only available in Linux 2.6 and later series
+kernels (and in the later parts of the 2.5 development series leading
+up to 2.6).  This man page does not apply to 2.4 and earlier.
+.P
+As well as this filesystem, there are a collection of files in the
+.B procfs
+filesystem (normally mounted at
+.BE /proc )
+which are used to control the NFS server.
+This manual page describes all of these files.
+.P
+The
+.I exportfs
+and
+.I mountd
+programs (part of the nfs-utils package) expect to find this
+filesystem mounted at
+.BR /proc/fs/nfs .
+If it is not mounted, they will fall-back on 2.4 style functionality.
+This involves accessing the NFS server via a systemcall.  This
+systemcall is scheduled to be removed after the 2.6 kernel series.
+.SH DETAILS
+The three files in the
+.B nfsd
+filesystem are:
+.TP
+.B exports
+This file contains a list of filesystems that are currently exported
+and clients that each filesystem is exported to, together with a list
+of export options for that client/filesystem pair.  This is similar
+to the
+.B /proc/fs/nfs/exports
+file in 2.4.
+One difference is that a client doesn't necessarily correspond to just
+one host.  It can respond to a large collection of hosts that are
+being treated identically.
+
+Each line of the file contains a path name, a client name, and a
+number of options in parentheses.  Any space, tab, newline or
+back-slash character in the path name or client name will be replaced
+by a backslash followed by the octal ASCII code for that character.
+
+.TP
+.B threads
+This file represents the number of
+.B nfsd
+thread currently running.  Reading it will show the number of
+threads.  Writing an ASCII decimal number will cause the number of
+threads to be changed (increased or decreased as necessary) to achieve
+that number.
+
+.TP
+.B filehandle
+This is a somewhat unusual file  in that what is read from it depends
+on what was just written to it.  It provides a transactional interface
+where a program can open the file, write a request, and read a
+response.  If two separate programs open, write, and read at the same
+time, their requests will not be mixed up.
+
+The request written to
+.B filehandle
+should be a client name, a path name, and a number of bytes.  This
+should be followed by a newline, with white-space separating the
+fields, and octal quoting of special characters.
+
+On writing this, the program will be able to read back a filehandle
+for that path as exported to the given client.  The filehandles length
+will be at most the number of bytes given.
+
+The filehandle will be represented in hex with a leading '\ex'.
+.PP
+The directory
+.B /proc/net/rpc
+in the
+.B procfs
+filesystem contains a number of files and directories.
+The files contain statistics that can be display using the
+.I nfsstat
+program.
+The directories contain information about various caches that the NFS
+server maintains to keep track of access permissions that different
+clients have for different filesystems.
+The caches are:
+
+.TP
+.B auth.domain
+This cache maps the name of a client (or domain) to an internal data
+structure.  The only access that is possible is to flush the cache.
+
+.TP
+.B auth.unix.ip
+This cache contains a mapping from IP address to the name of the
+authentication domain that the ipaddress should be treated as part of.
+
+.TP
+.B nfsd.export
+This cache contains a mapping from directory and domain to export
+options.
+
+.TP
+.B nfsd.fh
+This cache contains a mapping from domain and a filesystem identifier
+to a directory.   The filesystem identifier is stored in the
+filehandles and consists of a number indicating the type of identifier
+and a number of hex bytes indicating the content of the identifier.
+
+.PP
+Each directory representing a cache can hold from 1 to 3 files.  They
+are:
+.TP
+.B flush
+When a number of seconds since epoch (1 Jan 1970) is written to this
+file, all entries in the cache that were last updated before that file
+become invalidated and will be flushed out.  Writing 1 will flush
+everything.  This is the only file that will always be present.
+
+.TP
+.B content
+This file, if present, contains a textual representation of ever entry
+in the cache, one per line.  If an entry is still in the cache
+(because it is actively being used) but has expired or is otherwise
+invalid, it will be presented as a comment (with a leading hash
+character).
+
+.TP
+.B channel
+This file, if present, acts a channel for request from the kernel-based
+nfs server to be passed to a user-space program for handling.
+
+When the kernel needs some information which isn't in the cache, it
+makes a line appear in the
+.B channel
+file giving the key for the information.  A user-space program should
+read this, find the answer, and write a line containing the key, an
+expiry time, and the content.
+For example the kernel might make
+.ti +5
+nfsd 127.0.0.1
+.br
+appear in the
+.B auth.unix.ip/content
+file.  The user-space program might then write
+.ti +5
+nfsd 127.0.0.1 1057206953 localhost
+.br
+to indicate that 127.0.0.1 should map to localhost, atleast for now.
+
+If the program uses select(2) or poll(2) to discover if it can read
+from the
+.B channel
+then it will never see and end-of-file but when all requests have been
+answered, it will block until another request appears.
+
+.PP
+In the
+.B /proc
+filesystem there are 4 files that can be used to enabled extra tracing
+of nfsd and related code.  They are:
+.in +5
+.B /proc/sys/sunrpc/nfs_debug
+.br
+.B /proc/sys/sunrpc/nfsd_debug
+.br
+.B /proc/sys/sunrpc/nlm_debug
+.br
+.B /proc/sys/sunrpc/rpc_debug
+.br
+.in -5
+They control tracing for the NFS client, the NFS server, the Network
+Lock Manager (lockd) and the underlying RPC layer respectively.
+Decimal numbers can be read from or written to these files.  Each
+number represents a bit-pattern where bits that are set cause certain
+classes of tracing to be enabled.  Consult the kernel header files to
+find out what number correspond to what tracing.
+
+.SH SEE ALSO
+.BR rpc.nfsd (8),
+.BR exports (5),
+.BR nfsstat (8),
+.BR mountd (8)
+.BR exportfs (8).
+
+.SH AUTHOR
+NeilBrown
index 4cc6f8a..e178960 100644 (file)
@@ -8,7 +8,6 @@ OBJS    = nfsd.o
 DEPLIBS = $(TOP)support/lib/libfs.a
 LIBS   = -lnfs
 MAN8   = nfsd
-
 include $(TOP)rules.mk
 
 #