nfsdtop(8)

NAME

nfsdtop – display top-like NFS server I/O statistics

SYNOPSIS

nfsdtop [-aDdhnoqRrvw] [-b | -j | -J] [-C ip] [-c | -g | -u] [-G group] [-I file] [-i sec] [-N num] [-P file] [-p file] [-U user]

DESCRIPTION

The nfsdtop utility uses dtrace(1) to display a periodically updated table of NFS server read and write activity. Statistics are taken from the nfsd(8) read and write paths (nfsrvd_read(,, Fn, nfsvno_read, ,, Fn, nfsrvd_write, ,, and, Fn, nfsvno_write)) and coalesced by a chosen view.

Only the root user or users with dtrace(1) privileges can run this command.

A view selects the first column of the display. The default is the user view (‘-u’), where each row is a UID (or user name). The group view (‘-g’) and client view (‘-c’) instead coalesce by GID or IPv4 client address. Without ‘-j’, the last of ‘-c’, ‘-g’, or ‘-u’ wins.

UIDs, GIDs, and IPv4 addresses shown in a view are taken from NFS client credentials and addresses on the nfsd(8) paths. They often cannot be resolved on the nfsd host, so nfsdtop does not use getent(1) to name them as traffic is sampled; that lookup would likely be useless. The map files described in FILES supply those names. Command-line filters are different. A name given to ‘-U’, ‘-G’, or ‘-C’ is resolved once, first from the same map files and then via getent(1) or host(1), so the resulting UID, GID, or address can be compiled into the dtrace(1) predicates.

Each interval prints a header followed by a ‘total’ row and per-key rows sorted by combined read and write volume. Columns are the view key, combined TOTAL, WRITE(IN), an optional bar, and READ(OUT). Values are humanized bandwidth (bytes per second) unless ‘-b’ is given. When standard output is a terminal, the screen is redrawn in place and SIGWINCH resizes the layout.

OPTIONS

-a

Always enable color, even when standard output is not a terminal.

-b

Show bytes transferred during the interval instead of bandwidth. Cannot be combined with ‘-j’ or ‘-J’.

-C ip

Client filter. Only count I/O for the given IPv4 address or hostname (IPv4 only). A hostname given here is resolved once from the IP map (see -I) or host(1).

-c

View read/write activity by client.

-D

Enable debugger. Print raw dtrace(1) output and additional post-processor diagnostics.

-d

Debug. Print the generated dtrace(1) script to standard output and exit.

-G group

Group filter. Only count I/O for the given group name or GID. A name given here is resolved once from the group map (see -P) or getent(1).

-g

View read/write activity by group.

-h

Print usage statement and exit.

-I file

IP map file for naming observed client addresses (see DESCRIPTION). Default .nfsd.hosts in the current directory. Each non-comment line is an IPv4 address followed by a hostname.

-i sec

Set interval seconds. Default ‘2.0’. Must be at least 0.001.

-J

Output JSON for the client, group, and user views. Same as ‘-jcgu’.

-j

Output JSON formatted data. Each interval emits one object for the view total and one object per key. Objects contain time, ident, total_bytes, total_rate, read_bytes, read_rate, write_bytes, and write_rate.

-N num

Perform num samples and exit.

-n

Do not map observed UIDs, GIDs, or IPs through the map files.

-o

Force non-console output. Disable screen redraw and color.

-P file

Group map file for naming observed GIDs (see DESCRIPTION). Default .nfsd.group in the current directory. Format is group(5).

-p file

User map file for naming observed UIDs (see DESCRIPTION). Default .nfsd.passwd in the current directory. Format is passwd(5).

-q

Quiet. Hide informational messages.

-R

Redact potentially sensitive information. User, group, and client names that are not well-known system accounts are replaced with random strings of the same length. May also be enabled by setting NFSDTOP_REDACT in the environment.

-r

Raw view. Do not format output of dtrace(1).

-U user

User filter. Only count I/O for the given user name or UID. A name given here is resolved once from the user map (see -p) or getent(1).

-u

View read/write activity by user (default).

-v

Print version and exit.

-w

Wide view. Maximize width of the first column.

ENVIRONMENT

NFSDTOP_REDACT

If set to a non-empty value, enable redaction as with ‘-R’.

FILES

These files map identifiers from observed NFS traffic to names. getent(1) on the nfsd host is not used for that translation.

.nfsd.passwd

Default user map (‘-p’), looked up in the current directory.

.nfsd.group

Default group map (‘-P’), looked up in the current directory.

.nfsd.hosts

Default IP map (‘-I’), looked up in the current directory.

EXIT STATUS

The nfsdtop utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

Display per-user NFS server I/O, updated every two seconds:

nfsdtop

View activity by NFS client:

nfsdtop -c

Restrict the group view to ‘wheel’:

nfsdtop -g -G wheel

Count only I/O from one client and show bytes instead of bandwidth:

nfsdtop -c -C 192.0.2.10 -b

Emit one JSON sample for all views and exit:

nfsdtop -J -N 1

Print the generated DTrace script without running it:

nfsdtop -d

SEE ALSO

dtrace(1), dwatch(1), getent(1), nfsstat(1), group(5), passwd(5), gstat(8), iostat(8), nfsd(8)

HISTORY

The nfsdtop utility first appeared in FreeBSD 16.0.

AUTHORS

Devin Teske ⟨[email protected]⟩

BUGS

The client view and ‘-C’ filter support IPv4 only.