NFS client library
C Logos Shell Other
Latest commit df94ae9 Jul 8, 2017 @sahlberg pdu->timeout needs to be uint64_t
pdu->timeout is the timeout for for the pdu using the unix epoch but
expressed in ms, not seconds.
As such it must be 64 bit as on 32 bit we would have already wrapped the
timer.

Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
Permalink
Failed to load latest commit information.
aros aros: add licence to aros_compat.h Jun 8, 2014
doc UTILS: move nfs-cp from examples to utils May 24, 2015
examples Add example util for nfs_link() May 3, 2017
include pdu->timeout needs to be uint64_t Jul 8, 2017
lib Fix compiler warnings about cast from char* -> uint32_t* Jul 8, 2017
m4 build: add m4 directory to source tree Aug 23, 2015
mount don't call rpc_free_pdu() after rpc_queue_pdu() failure Mar 8, 2017
nfs don't call rpc_free_pdu() after rpc_queue_pdu() failure Mar 8, 2017
nfs4 NFS4: Add support to nfs_mount() Jul 6, 2017
nlm don't call rpc_free_pdu() after rpc_queue_pdu() failure Mar 8, 2017
nsm don't call rpc_free_pdu() after rpc_queue_pdu() failure Mar 8, 2017
packaging/RPM RPM: minor fixes to the RPM build Jun 17, 2017
portmap don't call rpc_free_pdu() after rpc_queue_pdu() failure Mar 8, 2017
rquota don't call rpc_free_pdu() after rpc_queue_pdu() failure Mar 8, 2017
tests TESTS: Tweak timeout test settings Jul 8, 2017
utils nfs-cp change uint64_t to size_t for the read/write wrappers Sep 21, 2016
win32 WIN32: Update the project file with nfs_v4.c (and the renamed nfs_v3.c) Jul 8, 2017
.gitignore Added ignore pattern for Windows intermediate files Nov 24, 2012
CHANGELOG New version : 2.0.0 Jun 16, 2017
COPYING proto files: add a simplified bsd licence to the dot-x files Jun 8, 2014
LICENCE-BSD.txt Include the BSD license text in a separate file Mar 29, 2015
LICENCE-GPL-3.txt update the licence text and proide an explicit copy of LGPL2.1 and GPL3 Mar 4, 2012
LICENCE-LGPL-2.1.txt update the licence text and proide an explicit copy of LGPL2.1 and GPL3 Mar 4, 2012
Makefile.am Add NFSv4 protocol definitions Dec 17, 2016
README README: clarify status of nfsv4 support. I.e. not yet functional. Jun 30, 2017
bootstrap bootstrap: use "exec" to replace the shell process instead of forking it Mar 8, 2017
configure.ac TESTS: Initial test directory. Jun 16, 2017
libnfs.pc.in libnfs.pc.in: fix pkg-config --cflags Dec 17, 2013
win32build.bat Try making the initial port used a little more random May 29, 2013

README

LIBNFS is a client library for accessing NFS shares over a network.

LIBNFS offers three different APIs, for different use :
1, RAW : A fully async low level RPC library for NFS protocols
This API is described in include/libnfs-raw.h
it offers a fully async interface to raw XDR encoded blobs.
This API provides very flexible and precise control of the RPC issued.

examples/nfsclient-raw.c provides examples on how to use the raw API

2, NFS ASYNC : A fully asynchronous library for high level vfs functions
This API is described by the *_async() functions in include/libnfs.h.
This API provides a fully async access to posix vfs like functions such as
stat(), read(), ...

examples/nfsclient-async.c provides examples on how to use this API


3, NFS SYNC : A synchronous library for high level vfs functions
This API is described by the *_sync() functions in include/libnfs.h.
This API provides access to posix vfs like functions such as
stat(), read(), ...

examples/nfsclient-sync.c provides examples on how to use this API

NFSv4:
======
NFSv4 is supported but only for the RAW ASYNC interface.
Examples/nfsv4-cat.c is a "simple" example to illustrate how to use
NFSv4 to connect to a server and read a file off the server.

SERVER SUPPORT:
===============
Libnfs supports building RPC servers.
Examples/portmapper-server.c is a small "portmapper" example written using
libnfs.

URL-FORMAT:
===========
Libnfs uses RFC2224 style URLs extended with some minor libnfs extensions.
The basic syntax of these URLs is :

nfs://<server|ipv4|ipv6>/path[?arg=val[&arg=val]*]

Arguments supported by libnfs are :
 tcp-syncnt=<int>  : Number of SYNs to send during the session establish
                     before failing setting up the tcp connection to the
                     server.
 uid=<int>         : UID value to use when talking to the server.
                     default it 65534 on Windows and getuid() on unixen.
 gid=<int>         : GID value to use when talking to the server.
                     default it 65534 on Windows and getgid() on unixen.
 readahead=<int>   : Enable readahead for files and set the maximum amount
                     of readahead to <int> bytes.
 auto-traverse-mounts=<0|1>
                   : Should libnfs try to traverse across nested mounts
                     automatically or not. Default is 1 == enabled.
 dircache=<0|1>    : Disable/enable directory caching. Enabled by default.
 autoreconnect=<-1|0|>=1>
                   : Control the auto-reconnect behaviour to the NFS session.
                    -1 : Try to reconnect forever on session failures.
                         Just like normal NFS clients do.
                     0 : Disable auto-reconnect completely and immediately
                         return a failure to the application.
                   >=1 : Retry to connect back to the server this many
                         times before failing and returing an error back
                         to the application.
 if=<interface>    : Interface name (e.g., eth1) to bind; requires `root`
 version=<3|4>     : NFS Version. Default is 3.
                     This is just a placeholder for now. NFSv4 support is not
		     yet functional.

Auto_traverse_mounts
====================
Normally in NFSv3 if a server has nested exports, for example if it would
export both /data and /data/tmp then a client would need to mount
both these exports as well.
The reason is because the NFSv3 protocol does not allow a client request
to return data for an object in a different filesystem/mount.
(legacy, but it is what it is. One reason for this restriction is to
guarantee that inodes are unique across the mounted system.)

This option, when enabled, will make libnfs perform all these mounts
internally for you. This means that one libnfs mount may now have files
with duplicate inode values so if you cache files based on inode
make sure you cache files based on BOTH st.st_ino and st.st_dev.


ROOT vs NON-ROOT
================
When running as root, libnfs tries to allocate a system port for its connection
to the NFS server. When running as non-root it will use a normal
ephemeral port.
Many NFS servers default to a mode where they do not allow non-system
ports from connecting.
These servers require you use the "insecure" export option in /etc/exports
in order to allow libnfs clients to be able to connect.

On Linux we can get around this restriction by setting the NET_BIND_SERVICE
capability for the application binary.

This is set up by running
    sudo setcap 'cap_net_bind_service=+ep' /path/to/executable
This capability allows the binary to use systems ports like this even when
not running as root. Thus if you set this capability for your application
you no longer need to edit the export on the NFS server to set "insecure".


I do not know what equivalent "capability" support is available on other
platforms. Please drop me an email if your os of choice has something similar
and I can add it to the README.


DOCUMENTATION
=============
libnfs sources ship with prebuilt manpage(s) in the doc directory.
If you change the manpage sources you need to manually regenerate the new
manpages by running
  cd doc
  make doc


PLATFORM support
=================
This is a truly multiplatform library.

Linux:  - tested with Ubuntu 10.04 - should work with others as well
Cygwin: - tested under 64bit win2k8.
MacOSX: - tested with SDK 10.4 (under Snow Leopard) - should also work with later SDKs and 64Bit
iOS:    - tested with iOS SDK 4.2 - running on iOS 4.3.x
FreeBSD:- tested with 8.2
Solaris
Windows:- tested on Windows 7 64 and Windows XP 32 using Visual Studio 10 (see README.win32.txt for build instructions)
        - tested on Windows 7 64 using MingW on Linux to cross-compile (Debian and Ubuntu tested)
Android:- tested with NDK r10e - running on Android 4.4 (should work starting from 2.3.3)
AROS: - Build with 'make -f aros/Makefile.AROS'


LD_PRELOAD
==========
examples/ld_nfs.c contains a LD_PRELOADable module that can be used to make
several standard utilities nfs aware.
It is still very incomplete but can be used for basic things such as cat and cp.
Patches to add more coverage is welcome.

Compile with :
gcc -fPIC -shared -o ld_nfs.so examples/ld_nfs.c -ldl -lnfs

Then try things like
LD_NFS_DEBUG=9 LD_PRELOAD=./ld_nfs.so cat nfs://127.0.0.1/data/tmp/foo123

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

This is just a toy preload module. Don't open bugs if it does not work. Send
patches to make it better instead.


RELEASE TARBALLS
================
Release tarballs are available at
https://sites.google.com/site/libnfstarballs/li



MAILING LIST
============
A libnfs mailing list is available at http://groups.google.com/group/libnfs
Announcements of new versions of libnfs will be posted to this list.