|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | 03-May-2022 | - |
| aros/ | H | 03-May-2022 | - | 301 | 211 |
| cmake/ | H | 12-Feb-2019 | - | 296 | 231 |
| doc/ | H | 03-May-2022 | - | 464 | 338 |
| examples/ | H | 03-May-2022 | - | 5,827 | 4,353 |
| include/ | H | 12-Feb-2019 | - | 5,352 | 1,648 |
| lib/ | H | 03-May-2022 | - | 17,402 | 14,013 |
| m4/ | H | 12-Feb-2019 | - | | |
| mount/ | H | 03-May-2022 | - | 975 | 719 |
| nfs/ | H | 03-May-2022 | - | 7,362 | 6,285 |
| nfs4/ | H | 03-May-2022 | - | 6,950 | 5,395 |
| nlm/ | H | 03-May-2022 | - | 1,008 | 755 |
| nsm/ | H | 03-May-2022 | - | 686 | 466 |
| packaging/RPM/ | H | 12-Feb-2019 | - | 408 | 314 |
| portmap/ | H | 03-May-2022 | - | 1,414 | 1,040 |
| rquota/ | H | 03-May-2022 | - | 709 | 501 |
| tests/ | H | 03-May-2022 | - | 5,418 | 3,596 |
| utils/ | H | 03-May-2022 | - | 782 | 633 |
| win32/ | H | 03-May-2022 | - | 2,120 | 1,981 |
| .gitignore | H A D | 12-Feb-2019 | 422 | 42 | 40 |
| CHANGELOG | H A D | 12-Feb-2019 | 2.1 KiB | 81 | 53 |
| COPYING | H A D | 12-Feb-2019 | 1.6 KiB | 40 | 29 |
| Makefile.am | H A D | 03-May-2022 | 321 | 15 | 12 |
| README | H A D | 12-Feb-2019 | 7.2 KiB | 177 | 138 |
| bootstrap | H A D | 12-Feb-2019 | 34 | 3 | 1 |
| configure.ac | H A D | 12-Feb-2019 | 7 KiB | 263 | 224 |
| libnfs.pc.in | H A D | 12-Feb-2019 | 291 | 15 | 12 |
| win32build.bat | H A D | 12-Feb-2019 | 3.5 KiB | 68 | 43 |
README
1LIBNFS is a client library for accessing NFS shares over a network.
2
3LIBNFS offers three different APIs, for different use :
41, RAW : A fully async low level RPC library for NFS protocols
5This API is described in include/libnfs-raw.h
6it offers a fully async interface to raw XDR encoded blobs.
7This API provides very flexible and precise control of the RPC issued.
8
9examples/nfsclient-raw.c provides examples on how to use the raw API
10
112, NFS ASYNC : A fully asynchronous library for high level vfs functions
12This API is described by the *_async() functions in include/libnfs.h.
13This API provides a fully async access to posix vfs like functions such as
14stat(), read(), ...
15
16examples/nfsclient-async.c provides examples on how to use this API
17
18
193, NFS SYNC : A synchronous library for high level vfs functions
20This API is described by the *_sync() functions in include/libnfs.h.
21This API provides access to posix vfs like functions such as
22stat(), read(), ...
23
24examples/nfsclient-sync.c provides examples on how to use this API
25
26NFSv4:
27======
28NFSv3 is the default but NFSv4 can be selected either by using the URL argument
29version=4 or programatically calling nfs_set_version(nfs, NFS_V4) before
30connecting to the server/share.
31
32SERVER SUPPORT:
33===============
34Libnfs supports building RPC servers.
35Examples/portmapper-server.c is a small "portmapper" example written using
36libnfs.
37
38URL-FORMAT:
39===========
40Libnfs uses RFC2224 style URLs extended with some minor libnfs extensions.
41The basic syntax of these URLs is :
42
43nfs://<server|ipv4|ipv6>/path[?arg=val[&arg=val]*]
44
45Arguments supported by libnfs are :
46 tcp-syncnt=<int> : Number of SYNs to send during the session establish
47 before failing setting up the tcp connection to the
48 server.
49 uid=<int> : UID value to use when talking to the server.
50 default it 65534 on Windows and getuid() on unixen.
51 gid=<int> : GID value to use when talking to the server.
52 default it 65534 on Windows and getgid() on unixen.
53 readahead=<int> : Enable readahead for files and set the maximum amount
54 of readahead to <int> bytes.
55 auto-traverse-mounts=<0|1>
56 : Should libnfs try to traverse across nested mounts
57 automatically or not. Default is 1 == enabled.
58 dircache=<0|1> : Disable/enable directory caching. Enabled by default.
59 autoreconnect=<-1|0|>=1>
60 : Control the auto-reconnect behaviour to the NFS session.
61 -1 : Try to reconnect forever on session failures.
62 Just like normal NFS clients do.
63 0 : Disable auto-reconnect completely and immediately
64 return a failure to the application.
65 >=1 : Retry to connect back to the server this many
66 times before failing and returing an error back
67 to the application.
68 if=<interface> : Interface name (e.g., eth1) to bind; requires `root`
69 version=<3|4> : NFS Version. Default is 3.
70 nfsport=<port> : Use this port for NFS instead of using the portmapper.
71 mountport=<port> : Use this port for the MOUNT protocol instead of
72 using portmapper. This argument is ignored for NFSv4
73 as it does not use the MOUNT protocol.
74
75Auto_traverse_mounts
76====================
77Normally in NFSv3 if a server has nested exports, for example if it would
78export both /data and /data/tmp then a client would need to mount
79both these exports as well.
80The reason is because the NFSv3 protocol does not allow a client request
81to return data for an object in a different filesystem/mount.
82(legacy, but it is what it is. One reason for this restriction is to
83guarantee that inodes are unique across the mounted system.)
84
85This option, when enabled, will make libnfs perform all these mounts
86internally for you. This means that one libnfs mount may now have files
87with duplicate inode values so if you cache files based on inode
88make sure you cache files based on BOTH st.st_ino and st.st_dev.
89
90
91ROOT vs NON-ROOT
92================
93When running as root, libnfs tries to allocate a system port for its connection
94to the NFS server. When running as non-root it will use a normal
95ephemeral port.
96Many NFS servers default to a mode where they do not allow non-system
97ports from connecting.
98These servers require you use the "insecure" export option in /etc/exports
99in order to allow libnfs clients to be able to connect.
100
101On Linux we can get around this restriction by setting the NET_BIND_SERVICE
102capability for the application binary.
103
104This is set up by running
105 sudo setcap 'cap_net_bind_service=+ep' /path/to/executable
106This capability allows the binary to use systems ports like this even when
107not running as root. Thus if you set this capability for your application
108you no longer need to edit the export on the NFS server to set "insecure".
109
110
111I do not know what equivalent "capability" support is available on other
112platforms. Please drop me an email if your os of choice has something similar
113and I can add it to the README.
114
115
116DOCUMENTATION
117=============
118libnfs sources ship with prebuilt manpage(s) in the doc directory.
119If you change the manpage sources you need to manually regenerate the new
120manpages by running
121 cd doc
122 make doc
123
124
125PLATFORM support
126=================
127This is a truly multiplatform library.
128
129Linux: - tested with Ubuntu 10.04 - should work with others as well
130Cygwin: - tested under 64bit win2k8.
131MacOSX: - tested with SDK 10.4 (under Snow Leopard) - should also work with later SDKs and 64Bit
132iOS: - tested with iOS SDK 4.2 - running on iOS 4.3.x
133FreeBSD:- tested with 8.2
134Solaris
135Windows:- tested on Windows 7 64 and Windows XP 32 using Visual Studio 10 (see README.win32.txt for build instructions)
136 - tested on Windows 7 64 using MingW on Linux to cross-compile (Debian and Ubuntu tested)
137Android:- tested with NDK r10e - running on Android 4.4 (should work starting from 2.3.3)
138AROS: - Build with 'make -f aros/Makefile.AROS'
139
140
141LD_PRELOAD
142==========
143examples/ld_nfs.c contains a LD_PRELOADable module that can be used to make
144several standard utilities nfs aware.
145It is still very incomplete but can be used for basic things such as cat and cp.
146Patches to add more coverage is welcome.
147
148Compile with :
149gcc -fPIC -shared -o ld_nfs.so examples/ld_nfs.c -ldl -lnfs
150
151Then try things like
152LD_NFS_DEBUG=9 LD_PRELOAD=./ld_nfs.so cat nfs://127.0.0.1/data/tmp/foo123
153
154LD_NFS_DEBUG=9 LD_PRELOAD=./ld_nfs.so cp nfs://127.0.0.1/data/tmp/foo123 nfs://127.0.0.1/data/tmp/foo123.copy
155
156LD_NFS_UID and LD_NFS_GID can be used to fake the uid andthe gid in the nfs context.
157This can be useful on "insecure" enabled NFS share to make the server trust you as a root.
158You can try to run as a normal user things like :
159LD_NFS_DEBUG=9 LD_NFS_UID=0 LD_NFS_GID=0 LD_PRELOAD=./ld_nfs.so chown root:root nfs://127.0.0.1/data/tmp/foo123
160
161This is just a toy preload module. Don't open bugs if it does not work. Send
162patches to make it better instead.
163
164
165RELEASE TARBALLS
166================
167Release tarballs are available at
168https://sites.google.com/site/libnfstarballs/li
169
170
171
172MAILING LIST
173============
174A libnfs mailing list is available at http://groups.google.com/group/libnfs
175Announcements of new versions of libnfs will be posted to this list.
176
177