From 928c5db128be787cb6819f075a45730a7b73c8ea Mon Sep 17 00:00:00 2001 From: neilbrown Date: Thu, 3 Jul 2003 06:14:10 +0000 Subject: [PATCH] new man page - nfsd.7 --- ChangeLog | 3 + config.mk.in | 2 + rules.mk | 22 ++--- utils/exportfs/Makefile | 1 + utils/exportfs/nfsd.man | 204 ++++++++++++++++++++++++++++++++++++++++ utils/nfsd/Makefile | 1 - 6 files changed, 221 insertions(+), 12 deletions(-) create mode 100644 utils/exportfs/nfsd.man diff --git a/ChangeLog b/ChangeLog index 463a301..6eda83a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,8 @@ + 2003-07-03 NeilBrown + * 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 diff --git a/config.mk.in b/config.mk.in index 18d4f39..d2cbea0 100644 --- a/config.mk.in +++ b/config.mk.in @@ -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) diff --git a/rules.mk b/rules.mk index 6796f19..27b81bc 100644 --- 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 7 8 9, cmd="$(MDCMD)" $(MANLOOP);) + @$(foreach s, 1 5 7 8 9, cmd="$(MICMD)" $(MANLOOP);) ifneq ($(PREFIX),) - @$(foreach s, 1 5 8 9, cmd="$(LNCMD)" $(MANLOOP);) + @$(foreach s, 1 5 7 8 9, cmd="$(LNCMD)" $(MANLOOP);) endif postscript:: @@ -113,7 +113,7 @@ ifneq ($(SRCS),) indent: $(INDENT) $(SRCS) endif - + ################################################################## # Handling of dependencies ################################################################## diff --git a/utils/exportfs/Makefile b/utils/exportfs/Makefile index 8cd7029..aa77540 100644 --- a/utils/exportfs/Makefile +++ b/utils/exportfs/Makefile @@ -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 index 0000000..b4806b4 --- /dev/null +++ b/utils/exportfs/nfsd.man @@ -0,0 +1,204 @@ +.\" +.\" nfsd(7) - The nfsd filesystem +.\" +.\" Copyright (C) 2003 Neil Brown +.\" 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 diff --git a/utils/nfsd/Makefile b/utils/nfsd/Makefile index 4cc6f8a..e178960 100644 --- a/utils/nfsd/Makefile +++ b/utils/nfsd/Makefile @@ -8,7 +8,6 @@ OBJS = nfsd.o DEPLIBS = $(TOP)support/lib/libfs.a LIBS = -lnfs MAN8 = nfsd - include $(TOP)rules.mk # -- 2.39.5