README

   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|ipv6>/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 DOCUMENTATION
  66 =============
  67 libnfs sources ship with prebuilt manpage(s) in the doc directory.
  68 If you change the manpage sources you need to manually regenerate the new
  69 manpages by running
  70   cd doc
  71   make doc
  72
  73 FUSE
  74 ====
  75 A simple FUSE filesystem built on libnfs can be found in
  76 examples/fuse_nfs.c
  77
  78 Compile using : gcc fuse_nfs.c -o fuse_nfs -lfuse -lnfs
  79 Mount using : sudo ./fuse_nfs -n nfs://<server>/<export> -m <mountpoint>
  80
  81
  82 PLATFORM support
  83 =================
  84 This is a truly multiplatform library.
  85
  86 Linux:  - tested with Ubuntu 10.04 - should work with others as well
  87 Cygwin: - tested under 64bit win2k8.
  88 MacOSX: - tested with SDK 10.4 (under Snow Leopard) - should also work with later SDKs and 64Bit
  89 iOS:    - tested with iOS SDK 4.2 - running on iOS 4.3.x
  90 FreeBSD:- tested with 8.2
  91 Solaris
  92 Windows:- tested on Windows 7 64 and Windows XP 32 using Visual Studio 10 (see README.win32.txt for build instructions)
  93 Android:
  94 AROS: - Build with 'make -f aros/Makefile.AROS'
  95
  96
  97 LD_PRELOAD
  98 ==========
  99 examples/ld_nfs.c contains a LD_PRELOADable module that can be used to make
 100 several standard utilities nfs aware.
 101 It is still very incomplete but can be used for basic things such as cat and cp.
 102 Patches to add more coverage is welcome.
 103
 104 Compile with :
 105 gcc -fPIC -shared -o ld_nfs.so examples/ld_nfs.c -ldl -lnfs
 106
 107 Then try things like
 108 LD_NFS_DEBUG=9 LD_PRELOAD=./ld_nfs.so cat nfs://127.0.0.1/data/tmp/foo123
 109
 110 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
 111
 112 This is just a toy preload module. Don't open bugs if it does not work. Send
 113 patches to make it better instead.
 114
 115
 116 RELEASE TARBALLS
 117 ================
 118 Release tarballs are available at
 119 https://sites.google.com/site/libnfstarballs/li
 120
 121
 122
 123 MAILING LIST
 124 ============
 125 A libnfs mailing list is available at http://groups.google.com/group/libnfs
 126 Announcements of new versions of libnfs will be posted to this list.
 127