1. nfsls(8)
3. nfsls(8)

NAME

nfsls - list files and directories on an NFS server

SYNOPSIS

nfsls [-aAbdhklmMLqTv] [-c count] [-C count] [-H hertz] [-S source]

DESCRIPTION

nfsls sends NFS version 3 READDIRPLUS (for directories), GETATTR (for files) or READLINK (for symlinks) RPC requests to an NFS server and lists the details of each filehandle passed to it on stdin. For directories, multiple READDIRPLUS requests are sent to retrieve an entire directory listing, if required. To perform the initial directory listing at the root of an NFS export, pipe the output from the nfsmount command to nfsls. Recursive directory lookups can be performed by piping the output of nfsls to another nfsls command, possibly with filters (grep, jq etc) in between.

Input and output filehandles are represented as a series of JSON objects (one per line) with the keys "host", "ip", "path", and "filehandle", where the value of the "filehandle" key is the hex representation of the NFS filehandle.

nfsls assumes an input filehandle is a directory if the "path" ends in a "/" and sends a READDIRPLUS, otherwise it sends a GETATTR. In either case it checks the result of the call and will switch to sending the other RPC if required. This behaviour can be overridden with the -d option which restricts it to sending GETATTR calls only. If a symlink is returned by either procedure, a READLINK RPC is sent to resolve the target name. Directory entries are displayed in the order returned by the server.

If the NFS server requires "secure" ports (<1024), nfsls will have to be run as root.

OPTIONS

-a

Display hidden files and directories (names starting with .) These are not displayed by default.

-A

Display IP addresses (instead of hostnames).

-b

In long listing (-l) mode, display file sizes in bytes. (Default is human readable.)

-c

Count of requests to send to each input filehandle before exiting. Note that multiple READDIRPLUS RPCs to load a full directory listing or READLINKs to lookup symlinks count as a single request. A summary of all responses is printed when the count is reached or the program is interrupted.

-C count

Count of requests to send to each input filehandle before exiting. Note that multiple READDIRPLUS RPCs to load a full directory listing or READLINKs to lookup symlinks count as a single request. An fping(8) compatible parseable summary is printed when the count is reached or the program is interrupted.

-d

List directories instead of their contents. This forces nfsls to only send GETATTR calls.

-g

In long listing (-l) mode, display file sizes in gigabytes. (Default is human readable.) Files that have a nonzero size but that are less than 1GB are shown as >0 to distinguish them from zero length files.

-h

In long listing (-l) mode, display file sizes in human readable format. This selects whichever unit is the most compact to display in 4 digits of precision. This is the default.

-H hertz

The polling frequency in Hertz when in looping (-L) or counting (-c) modes. This is the number of requests sent to each target filehandle per second. Note that for larger directories, multiple READDIRPLUS RPCs can be sent but are only counted as a single request. Default = 1.

-k

In long listing (-l) mode, display file sizes in kilobytes. (Default is human readable.) Files that have a nonzero size but that are less than 1KB are shown as >0 to distinguish them from zero length files.

-l

Display a long listing similar to ls -l. This includes the file type and permissions bits, the number of links to the file, the owner's user and group names, the size in bytes, the date and time in ISO 8601 format, the server's hostname (or IP address with -A) and the filename (and the target if it's a symlink).

-L

Loop forever. Exit loop with Ctrl-c. A summary of all responses is printed when the program is interrupted.

-m

In long listing (-l) mode, display file sizes in megabytes. (Default is human readable.) Files that have a nonzero size but that are less than 1MB are shown as >0 to distinguish them from zero length files.

-M

Query the RPC portmapper on the server to lookup the NFS port. Otherwise connect directly to the standard port (2049). Uses UDP by defa ult or TCP if the -T option is specified.

-q

Quiet. In looping and counting modes, only print a summary not each individual response.

-S source

Use the specified source IP address for request packets.

-t

In long listing (-l) mode, display file sizes in terabytes. (Default is human readable.) Files that have a nonzero size but that are less than 1TB are shown as >0 to distinguish them from zero length files.

-T

Use TCP to connect to server. Default = UDP.

-v

Display debug output on stderr.

EXAMPLES

Typically nfsls will use a filehandle obtained from the output of the nfsmount command:

sudo sh -c "nfsmount dumpy | nfsls"

Since both commands typically need root privileges (to bind to a "secure" port) they can be run with a single subshell under sudo.

If the check is being run repeatedly, there is no need to query the fileserver with nfsmount every time. Since the root filehandles shouldn't change, the output can be stored in a file:

sudo nfsmount dumpy > dumpy.nfs

and used by subsequent commands:

sudo nfsls -C 5 < dumpy.nfs

Filters can also be used to do recursive lookups, for example to list the contents of the "/var/log/" directory:

sudo sh -c "nfsmount dumpy:/ | nfsls | grep var | nfsls | grep log | nfsls"

This may not be required on all NFS servers if the MOUNT daemon allows listing unexported subdirectories:

sudo sh -c "nfsmount dumpy:/var/log | nfsls"

RETURN VALUES

nfsls will return 0 if all requests to all targets received successful responses. Nonzero exit codes indicate a failure. 1 is an RPC error, 2 is a name resolution failure, 3 is an initialisation failure (typically bad arguments).

AUTHOR

Matt Provost, mprovost@termcap.net

COPYRIGHT

Copyright 2017 Matt Provost
RPC files Copyright Sun Microsystems
NFSv4 files Copyright IETF

2. January 2017
3. nfsls(8)