nfs.man: escape ' nroff for proper rendering, thanks to Simon Paillard (Closes: ...
[nfs-utils.git] / README
1 This is version 1.1.0 of nfs-utils, the Linux NFS utility package.
2
3
4 0. PROJECT RESOURCES
5
6 Home page:  http://sourceforge.net/projects/nfs/
7
8 To use the 'gss' support you must have kerberos-5 development 
9 libraries installed.
10 Otherwise use  "--disable-gss"
11
12 To use nfsv4 support you need libevent and libnfsidmap development
13 libraries.  They are available from 
14    http://www.monkey.org/~provos/libevent/
15    http://www.citi.umich.edu/projects/nfsv4/linux/libnfsidmap/
16 Otherwise use --disable-nfsv4
17
18
19 1. COMPILING
20
21 Unpack the sources and run these commands:
22
23     # ./configure
24     # make
25
26 To install binaries and documenation, run this command:
27
28     # make install
29
30
31 2. COMPILING FROM GIT
32
33 Getting nfs-utils for the first time:
34
35         git clone git://linux-nfs.org/nfs-utils
36
37 Updating to the latest head after you've already got it.
38
39         git pull
40
41 Building requires that autotools be installed.  To invoke them
42 simply
43
44         sh autogen.sh
45
46 Finally, build as usual as above.
47
48 3. DAEMON STARTUP ORDER
49
50 This nfs-utils packages does not provide any scripts for starting
51 various daemons as most distributions replace them with their own, so
52 any scripts we package would not get much testing.
53 Instead, we explain the dependencies involved in startup so that
54 scripts can be written to work correctly.
55
56 3.0   PREREQUISITES 
57
58    Name service (host name lookup) should be working before any
59    NFS services are started.
60
61    "portmap" must be running before any NFS services (server or
62    client) are started.
63    
64    Normally network interfaces should be configured first as well,
65    though this isn't critical for the NFS server (providing name
66    service is handled locally).
67    
68 3.1.  SERVER STARTUP
69
70
71    A/  mount -t nfsd /proc/fs/nfsd
72       This filesystem needs to be mount before most daemons,
73       particularly exportfs, mountd, svcgssd, idmapd.
74       It could be mounted once, or the script that starts each daemon
75       could test if it is mounted and mount it if not.
76
77    B/ svcgssd ; idmapd
78        These supply services to nfsd and so should be started before
79        rpc.nfsd.  Where they come between mounting the nfsd filesystem
80        and starting the nfsd server is not important.
81        idmapd is only needed for NFSv4 support.
82        svcgssd is only needed if exportfs NFS filesystem with crypto-
83        security (Kerberos or SPKM3).
84
85    C/ exportfs -av ; rpc.mountd
86        It is important that exportfs be run before mountd so that
87        mountd is working from current information (in
88        /var/lib/nfs/etab).
89        It is also important that both of these are run before
90        rpc.nfsd.
91        If not, any NFS requests that arrive before mountd is started
92        will get replied to with a 'Stale NFS File handle' error.
93
94    D/ rpc.statd --no-notify
95        It is best if statd is started before nfsd though this isn't
96        critical.  Certainly it should be at most a few seconds after
97        nfsd.
98        When nfsd starts it will start lockd. If lockd then receives a
99        lock request it will communicate with statd.  If statd is not
100        running lockd will retry, but it won't wait forever for a
101        reply.
102        Note that if statd is started before nfsd, the --no-notify
103        option must be used.  If notify requests are sent out before
104        nfsd start, clients may try to reclaim locks and, on finding
105        that lockd isn't running, they will give up and never reclaim
106        the lock.
107        rpc.statd is only needed for NFSv2 and NFSv3 support.
108
109    E/ rpc.nfsd
110        Starting nfsd will automatically start lockd.  The nfs server
111        will now be fully active and respond to any requests from
112        clients.
113        
114    F/ sm-notify
115        This will notify any client which might have locks from before
116        a reboot to try to reclaim their locks.  This should start
117        immediately after rpc.nfsd is started so that clients have a
118        chance to reclaim locks within the 90 second grace period.
119        sm-notify is only needed for NFSv2 and NFSv3 support.
120
121
122 3.2.  CLIENT STARTUP
123
124    A/ sm-notify
125       This should be run shortly after boot and before any NFS
126       filesystems are mounted with remote-locking support -
127       filesystems can be mounted with "-o nolock" before sm-notify.
128       This is appropriate for '/', '/usr', and '/var'.
129
130    B/ gssd ; idmapd
131       idmapd should be started before mounting any NFSv4 filesystems.
132       gssd should be started before mounting any NFS filesystems
133       securely (with Kerberos of SPKM3).
134
135    C/ statd should be run before any NFSv2 or NFSv3 filesystem is
136       mounted with remote locking (i.e. without -o nolock).
137       'mount' will try to use "/usr/sbin/start-statd" to start statd
138       if it is not already running, so there is no need to explicitly
139       start statd in boot-time scripts.
140
141 3.3.  SERVER/CLIENT INTERACTIONS
142
143    A/ sm-notify
144       Both the server and the client need sm-notify to be run.
145       It should be run after the NFS server is started, but before
146       and NFS filesystems are mounted with remote locking.
147
148    B/ rpc.statd
149       Both the server and the client need rpc.statd to be running.
150       Each should try to start when they need it.
151
152    C/ idmapd
153
154       Both the server and client need idmapd to be running.  If idmapd
155       is started (for the client) before starting nfsd the 'nfsd'
156       filesystem is mounted, then idmapd should be sent a HUP signal
157       afterwards to signal that the server channels should be opened.
158
159    
160       
161
162 Share And Enjoy!
163
164     --  the nfs-utils developers
165         <linux-nfs@vger.kernel.org>