| 1 | LIBNFS is a client library for accessing NFS shares over a network. |
| 2 | |
| 3 | LIBNFS offers three different APIs, for different use : |
| 4 | 1, RAW : A fully async low level RPC library for NFS protocols |
| 5 | This API is described in include/libnfs-raw.h |
| 6 | it offers a fully async interface to raw XDR encoded blobs. |
| 7 | This API provides very flexible and precise control of the RPC issued. |
| 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 |
| 12 | This API is described by the *_async() functions in include/libnfs.h. |
| 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 |
| 20 | This API is described by the *_sync() functions in include/libnfs.h. |
| 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 | |
| 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. |
| 41 | |
| 42 | |
| 43 | ROOT vs NON-ROOT |
| 44 | ================ |
| 45 | When running as root, libnfs tries to allocate a system port for its connection |
| 46 | to the NFS server. When running as non-root it will use a normal |
| 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 | |
| 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 | |
| 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 | |
| 73 | |
| 74 | PLATFORM support |
| 75 | ================= |
| 76 | This is a truly multiplatform library. |
| 77 | |
| 78 | Linux: - tested with Ubuntu 10.04 - should work with others as well |
| 79 | Cygwin: - tested under 64bit win2k8. |
| 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 |
| 82 | FreeBSD:- tested with 8.2 |
| 83 | Solaris |
| 84 | Windows:- tested on Windows 7 64 and Windows XP 32 using Visual Studio 10 (see README.win32.txt for build instructions) |
| 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 | |
| 112 | |
| 113 | |
| 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. |
| 118 | |