1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2020, 2026 Devin Teske <dteske@FreeBSD.org> 5.\" 6.Dd September 4, 2026 7.Dt NFSDTOP 8 8.Os 9.Sh NAME 10.Nm nfsdtop 11.Nd display top-like NFS server I/O statistics 12.Sh SYNOPSIS 13.Nm 14.Op Fl aDdhnoqRrvw 15.Op Fl b | Fl j | Fl J 16.Op Fl C Ar ip 17.Op Fl c | Fl g | Fl u 18.Op Fl G Ar group 19.Op Fl I Ar file 20.Op Fl i Ar sec 21.Op Fl N Ar num 22.Op Fl P Ar file 23.Op Fl p Ar file 24.Op Fl U Ar user 25.Sh DESCRIPTION 26The 27.Nm 28utility uses 29.Xr dtrace 1 30to display a periodically updated table of NFS 31server read and write activity. 32Statistics are taken from the 33.Xr nfsd 8 34read and write paths 35.Pq Fn nfsrvd_read , Fn nfsvno_read , Fn nfsrvd_write , and Fn nfsvno_write 36and coalesced by a chosen 37.Em view . 38.Pp 39Only the root user or users with 40.Xr dtrace 1 41privileges can run this command. 42.Pp 43A view selects the first column of the display. 44The default is the user view 45.Pq Ql Fl u , 46where each row is a UID 47.Pq or user name . 48The group view 49.Pq Ql Fl g 50and client view 51.Pq Ql Fl c 52instead coalesce by GID or IPv4 client address. 53Without 54.Ql Fl j , 55the last of 56.Ql Fl c , 57.Ql Fl g , 58or 59.Ql Fl u 60wins. 61.Pp 62UIDs, GIDs, and IPv4 addresses shown in a view are taken from NFS client 63credentials and addresses on the 64.Xr nfsd 8 65paths. 66They often cannot be resolved on the nfsd host, so 67.Nm 68does not use 69.Xr getent 1 70to name them as traffic is sampled; that lookup would likely be useless. 71The map files described in 72.Sx FILES 73supply those names. 74Command-line filters are different. 75A name given to 76.Ql Fl U , 77.Ql Fl G , 78or 79.Ql Fl C 80is resolved once, first from the same map files and then via 81.Xr getent 1 82or 83.Xr host 1 , 84so the resulting UID, GID, or address can be compiled into the 85.Xr dtrace 1 86predicates. 87.Pp 88Each interval prints a header followed by a 89.Ql total 90row and per-key rows sorted by combined read and write volume. 91Columns are the view key, 92combined TOTAL, 93WRITE(IN), 94an optional bar, 95and READ(OUT). 96Values are humanized bandwidth 97.Pq bytes per second 98unless 99.Ql Fl b 100is given. 101When standard output is a terminal, 102the screen is redrawn in place and 103.Dv SIGWINCH 104resizes the layout. 105.Sh OPTIONS 106.Bl -tag -width "-I file" 107.It Fl a 108Always enable color, 109even when standard output is not a terminal. 110.It Fl b 111Show bytes transferred during the interval instead of bandwidth. 112Cannot be combined with 113.Ql Fl j 114or 115.Ql Fl J . 116.It Fl C Ar ip 117Client filter. 118Only count I/O for the given IPv4 address or hostname 119.Pq IPv4 only . 120A hostname given here is resolved once from the IP map 121.Pq see Fl I 122or 123.Xr host 1 . 124.It Fl c 125View read/write activity by client. 126.It Fl D 127Enable debugger. 128Print raw 129.Xr dtrace 1 130output and additional post-processor diagnostics. 131.It Fl d 132Debug. 133Print the generated 134.Xr dtrace 1 135script to standard output and exit. 136.It Fl G Ar group 137Group filter. 138Only count I/O for the given group name or GID. 139A name given here is resolved once from the group map 140.Pq see Fl P 141or 142.Xr getent 1 . 143.It Fl g 144View read/write activity by group. 145.It Fl h 146Print usage statement and exit. 147.It Fl I Ar file 148IP map file for naming observed client addresses 149.Pq see DESCRIPTION . 150Default 151.Pa .nfsd.hosts 152in the current directory. 153Each non-comment line is an IPv4 address followed by a hostname. 154.It Fl i Ar sec 155Set interval seconds. 156Default 157.Ql 2.0 . 158Must be at least 0.001. 159.It Fl J 160Output JSON for the client, group, and user views. 161Same as 162.Ql Fl jcgu . 163.It Fl j 164Output JSON formatted data. 165Each interval emits one object for the view total and one object per key. 166Objects contain 167.Li time , 168.Li ident , 169.Li total_bytes , 170.Li total_rate , 171.Li read_bytes , 172.Li read_rate , 173.Li write_bytes , 174and 175.Li write_rate . 176.It Fl N Ar num 177Perform 178.Ar num 179samples and exit. 180.It Fl n 181Do not map observed UIDs, GIDs, or IPs through the map files. 182.It Fl o 183Force non-console output. 184Disable screen redraw and color. 185.It Fl P Ar file 186Group map file for naming observed GIDs 187.Pq see DESCRIPTION . 188Default 189.Pa .nfsd.group 190in the current directory. 191Format is 192.Xr group 5 . 193.It Fl p Ar file 194User map file for naming observed UIDs 195.Pq see DESCRIPTION . 196Default 197.Pa .nfsd.passwd 198in the current directory. 199Format is 200.Xr passwd 5 . 201.It Fl q 202Quiet. 203Hide informational messages. 204.It Fl R 205Redact potentially sensitive information. 206User, group, and client names that are not well-known system accounts are 207replaced with random strings of the same length. 208May also be enabled by setting 209.Ev NFSDTOP_REDACT 210in the environment. 211.It Fl r 212Raw view. 213Do not format output of 214.Xr dtrace 1 . 215.It Fl U Ar user 216User filter. 217Only count I/O for the given user name or UID. 218A name given here is resolved once from the user map 219.Pq see Fl p 220or 221.Xr getent 1 . 222.It Fl u 223View read/write activity by user 224.Pq default . 225.It Fl v 226Print version and exit. 227.It Fl w 228Wide view. 229Maximize width of the first column. 230.El 231.Sh ENVIRONMENT 232.Bl -tag -width NFSDTOP_REDACT 233.It Ev NFSDTOP_REDACT 234If set to a non-empty value, enable redaction as with 235.Ql Fl R . 236.El 237.Sh FILES 238These files map identifiers from observed NFS traffic to names. 239.Xr getent 1 240on the nfsd host is not used for that translation. 241.Pp 242.Bl -tag -width ".nfsd.passwd" -compact 243.It Pa .nfsd.passwd 244Default user map 245.Pq Ql Fl p , 246looked up in the current directory. 247.It Pa .nfsd.group 248Default group map 249.Pq Ql Fl P , 250looked up in the current directory. 251.It Pa .nfsd.hosts 252Default IP map 253.Pq Ql Fl I , 254looked up in the current directory. 255.El 256.Sh EXIT STATUS 257.Ex -std 258.Sh EXAMPLES 259Display per-user NFS 260server I/O, updated every two seconds: 261.Bd -literal -offset indent 262nfsdtop 263.Ed 264.Pp 265View activity by NFS client: 266.Bd -literal -offset indent 267nfsdtop -c 268.Ed 269.Pp 270Restrict the group view to 271.Ql wheel : 272.Bd -literal -offset indent 273nfsdtop -g -G wheel 274.Ed 275.Pp 276Count only I/O from one client and show bytes instead of bandwidth: 277.Bd -literal -offset indent 278nfsdtop -c -C 192.0.2.10 -b 279.Ed 280.Pp 281Emit one JSON sample for all views and exit: 282.Bd -literal -offset indent 283nfsdtop -J -N 1 284.Ed 285.Pp 286Print the generated DTrace script without running it: 287.Bd -literal -offset indent 288nfsdtop -d 289.Ed 290.Sh SEE ALSO 291.Xr dtrace 1 , 292.Xr dwatch 1 , 293.Xr getent 1 , 294.Xr nfsstat 1 , 295.Xr group 5 , 296.Xr passwd 5 , 297.Xr gstat 8 , 298.Xr iostat 8 , 299.Xr nfsd 8 300.Sh HISTORY 301The 302.Nm 303utility first appeared in 304.Fx 16.0 . 305.Sh AUTHORS 306.An Devin Teske Aq Mt dteske@FreeBSD.org 307.Sh BUGS 308The client view and 309.Ql Fl C 310filter support IPv4 only. 311