Commit | Line | Data |
---|---|---|
dabf4152 AM |
1 | LIBNFS is a client library for accessing NFS shares over a network. |
2 | ||
3 | LIBNFS offers three different APIs, for different use : | |
ee872606 | 4 | 1, RAW : A fully async low level RPC library for NFS protocols |
dabf4152 AM |
5 | This API is described in include/libnfs-raw.h |
6 | it offers a fully async interface to raw XDR encoded blobs. | |
ee872606 | 7 | This API provides very flexible and precise control of the RPC issued. |
dabf4152 AM |
8 | |
9 | examples/nfsclient-raw.c provides examples on how to use the raw API | |
10 | ||
11 | 2, NFS ASYNC : A fully asynchronous library for high level vfs functions | |
ee872606 | 12 | This API is described by the *_async() functions in include/libnfs.h. |
dabf4152 AM |
13 | This API provides a fully async access to posix vfs like functions such as |
14 | stat(), read(), ... | |
15 | ||
16 | examples/nfsclient-async.c provides examples on how to use this API | |
17 | ||
18 | ||
19 | 3, NFS SYNC : A synchronous library for high level vfs functions | |
ee872606 | 20 | This API is described by the *_sync() functions in include/libnfs.h. |
dabf4152 AM |
21 | This API provides access to posix vfs like functions such as |
22 | stat(), read(), ... | |
23 | ||
24 | examples/nfsclient-sync.c provides examples on how to use this API | |
25 | ||
ee872606 RRS |
26 | URL-FORMAT: |
27 | =========== | |
28 | Libnfs uses RFC2224 style URLs extended with libnfs specific url arguments some minor extensions. | |
29 | The basic syntax of these URLs is : | |
30 | ||
31 | nfs://<server|ipv4>/path[?arg=val[&arg=val]*] | |
32 | ||
33 | Arguments supported by libnfs are : | |
34 | tcp-syncnt=<int> : Number of SYNs to send during the session establish | |
35 | before failing setting up the tcp connection to the | |
36 | server. | |
37 | uid=<int> : UID value to use when talking to the server. | |
38 | default it 65534 on Windows and getuid() on unixen. | |
39 | gid=<int> : GID value to use when talking to the server. | |
40 | default it 65534 on Windows and getgid() on unixen. | |
dabf4152 AM |
41 | |
42 | ||
43 | ROOT vs NON-ROOT | |
44 | ================ | |
45 | When running as root, libnfs tries to allocate a system port for its connection | |
ee872606 | 46 | to the NFS server. When running as non-root it will use a normal |
dabf4152 AM |
47 | ephemeral port. |
48 | Many NFS servers default to a mode where they do not allow non-system | |
49 | ports from connecting. | |
50 | These servers require you use the "insecure" export option in /etc/exports | |
51 | in order to allow libnfs clients to be able to connect. | |
52 | ||
5670ec6e AM |
53 | Some versions of Linux support special capabilities that can be assigned to |
54 | programs to allow non-root users to bind to system ports. | |
55 | This is set up by running | |
56 | sudo setcap 'cap_net_bind_service=+ep' /path/to/executable | |
57 | When libnfs is linked against an executable with this special capability | |
58 | assigned to it, libnfs may be able to use system ports even when executing | |
59 | under the privilege of a non-root user account. | |
60 | ||
61 | This is highly non-portable so IF this works on your linux system, count | |
62 | yourself lucky. | |
63 | ||
64 | ||
ee872606 RRS |
65 | FUSE |
66 | ==== | |
67 | A simple FUSE filesystem built on libnfs can be found in | |
68 | examples/fuse_nfs.c | |
69 | ||
70 | Compile using : gcc fuse_nfs.c -o fuse_nfs -lfuse -lnfs | |
71 | Mount using : sudo ./fuse_nfs -n nfs://<server>/<export> -m <mountpoint> | |
72 | ||
5670ec6e | 73 | |
3be27335 | 74 | PLATFORM support |
dabf4152 | 75 | ================= |
ee872606 | 76 | This is a truly multiplatform library. |
dabf4152 | 77 | |
ee872606 | 78 | Linux: - tested with Ubuntu 10.04 - should work with others as well |
3be27335 | 79 | Cygwin: - tested under 64bit win2k8. |
dabf4152 AM |
80 | MacOSX: - tested with SDK 10.4 (under Snow Leopard) - should also work with later SDKs and 64Bit |
81 | iOS: - tested with iOS SDK 4.2 - running on iOS 4.3.x | |
3be27335 | 82 | FreeBSD:- tested with 8.2 |
ee872606 | 83 | Solaris |
5670ec6e | 84 | Windows:- tested on Windows 7 64 and Windows XP 32 using Visual Studio 10 (see README.win32.txt for build instructions) |
ee872606 RRS |
85 | Android: |
86 | AROS: - Build with 'make -f aros/Makefile.AROS' | |
87 | ||
88 | ||
89 | LD_PRELOAD | |
90 | ========== | |
91 | examples/ld_nfs.c contains a LD_PRELOADable module that can be used to make | |
92 | several standard utilities nfs aware. | |
93 | It is still very incomplete but can be used for basic things such as cat and cp. | |
94 | Patches to add more coverage is welcome. | |
95 | ||
96 | Compile with : | |
97 | gcc -fPIC -shared -o ld_nfs.so examples/ld_nfs.c -ldl -lnfs | |
98 | ||
99 | Then try things like | |
100 | LD_NFS_DEBUG=9 LD_PRELOAD=./ld_nfs.so cat nfs://127.0.0.1/data/tmp/foo123 | |
101 | ||
102 | LD_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 | |
103 | ||
104 | This is just a toy preload module. Don't open bugs if it does not work. Send | |
105 | patches to make it better instead. | |
106 | ||
107 | ||
108 | RELEASE TARBALLS | |
109 | ================ | |
110 | Release tarballs are available at https://sites.google.com/site/libnfstarballs/li | |
111 | ||
3be27335 AM |
112 | |
113 | ||
ee872606 RRS |
114 | MAILING LIST |
115 | ============ | |
116 | A libnfs mailing list is available at http://groups.google.com/group/libnfs | |
117 | Announcements of new versions of libnfs will be posted to this list. | |
3be27335 | 118 |