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