NFSTEST_ALLOC(1)

📦 version 3.2, in debian trixie, fedora 43, fedora 44, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NFSTEST_ALLOC — space reservation tests 💖

okay bestie, so this is nfstest_alloc from the nfstest manual (that's the manual name, NFSTEST_ALLOC(1), iykyk), and it's literally the whole vibe of "reserve me some disk space pls" but as a test suite. sit down, get comfy 🫶

✨ SYNOPSIS ✨

nfstest_alloc --server <server> [options]

🌸 DESCRIPTION 🌸

so the whole point here is verifying that space reservations actually work right, so apps can reserve or unreserve space for a file. the system call in the spotlight is fallocate, and it's used to manipulate the allocated disk space for a file — either preallocate it or deallocate it. and for filesystems that support the fallocate system call, preallocation is done quickly by allocating blocks and marking them as uninitialized, which means no I/O to the data blocks needed at all. that's so much faster than creating a file and filling it with zeros. no cap. 🔥

the basic allocate tests verify the disk space is actually preallocated or reserved for the given range by filling up the device after the allocation and making sure data can be written to the allocated range without any problems. also, anything written outside the allocated range will fail with NFS4ERR_NOSPC when there's no more space left on the device. and flip side? deallocating space gives the disk space back, so it can be used by either the same file on regions that aren't already preallocated, or by different files, with zero risk of getting a no-space error. slay. 💅

performance testing using ALLOCATE versus initializing a file to all zeros is also included, and the performance comparison is done with different file sizes. ⭐

some tests go full protocol level — taking a packet trace and inspecting the actual packets sent to the server or servers. main character behavior, honestly.

negative testing is included whenever possible, because some testing just can't be done at the protocol level: the fallocate system call does some error checking of its own and the NFS client won't even send an ALLOCATE or DEALLOCATE operation to the server, letting the server deal with the error. negative tests include trying to allocate an invalid range, having an invalid value for either the offset or the length, trying to allocate or deallocate a region on a file opened as read only, or the file being a non-regular file type. 💀

✨ OPTIONS ✨

  • --version — show program's version number and exit
  • -h, --help — show this help message and exit
  • -f FILE, --file=FILE — File where options are specified besides the system wide file /etc/nfstest, user wide file $HOME/.nfstest or in the current directory .nfstest file

🌈 NFS specific options:

  • -s SERVER, --server=SERVER — Server name or IP address
  • -e EXPORT, --export=EXPORT — Exported file system to mount [default: '/']
  • --nfsversion=NFSVERSION — NFS version, e.g., 3, 4, 4.1, etc. [default: 4.2]
  • -m MTPOINT, --mtpoint=MTPOINT — Mount point [default: '/mnt/t']
  • -p PORT, --port=PORT — NFS server port [default: 2049]
  • --proto=PROTO — NFS protocol name [default: 'tcp']
  • --sec=SEC — Security flavor [default: 'sys']
  • --nconnect=NCONNECT — Multiple TCP connections option [default: '1']
  • -o MTOPTS, --mtopts=MTOPTS — Mount options [default: 'hard,rsize=4096,wsize=4096']
  • --datadir=DATADIR — Data directory where files are created, directory is created on the mount point [default: '']

🎀 Logging options:

  • -v VERBOSE, --verbose=VERBOSE — Verbose level for debug messages [default: 'opts|info|dbg1|dbg2|dbg3']
  • --tverbose=TVERBOSE — Verbose level for test messages [default: '1']
  • --createlog — Create log file
  • --rexeclog — Create rexec log files
  • --warnings — Display warnings
  • --tag=TAG — Informational tag, it is displayed as an INFO message [default: '']
  • --notty — Do not use terminal colors on output
  • --isatty — Use terminal colors on output -- useful when running with nohup

🦋 Packet trace options:

  • --createtraces — Create a packet trace for each test
  • --tbsize=TBSIZE — Capture buffer size for tcpdump [default: 192k]
  • --trcdelay=TRCDELAY — Seconds to delay before stopping packet trace [default: 2.0]
  • --keeptraces — Do not remove any trace files [default: remove trace files if no errors]
  • --rmtraces — Remove trace files [default: remove trace files if no errors]
  • -i INTERFACE, --interface=INTERFACE — Device interface [default: automatically selected]

🍓 File options:

  • --nfiles=NFILES — Number of files to create [default: 2]
  • --filesize=FILESIZE — File size to use for test files [default: 64k]
  • --rsize=RSIZE — Read size to use when reading files [default: 4k]
  • --wsize=WSIZE — Write size to use when writing files [default: 4k]
  • --iodelay=IODELAY — Seconds to delay I/O operations [default: 0.1]
  • --offset-delta=OFFSET_DELTA — Read/Write offset delta [default: 4k]

💜 Path options:

  • --sudo=SUDO — Full path of binary for sudo [default: '/usr/bin/sudo']
  • --kill=KILL — Full path of binary for kill [default: '/usr/bin/kill']
  • --nfsstat=NFSSTAT — Full path of binary for nfsstat [default: '/usr/sbin/nfsstat']
  • --tcpdump=TCPDUMP — Full path of binary for tcpdump [default: '/usr/sbin/tcpdump']
  • --iptables=IPTABLES — Full path of binary for iptables [default: '/usr/sbin/iptables']
  • --messages=MESSAGES — Full path of log messages file [default: '/var/log/messages']
  • --trcevents=TRCEVENTS — Full path of tracing events directory [default: '/sys/kernel/debug/tracing/events']
  • --trcpipe=TRCPIPE — Full path of trace pipe file [default: '/sys/kernel/debug/tracing/trace_pipe']
  • --tmpdir=TMPDIR — Temporary directory [default: '/tmp']

🧚 Debug options:

  • --nocleanup — Do not cleanup created files
  • --notimestamps — Do not display timestamps in debug messages
  • --bugmsgs=BUGMSGS — File containing test messages to mark as bugs if they failed
  • --nomount — Do not mount server and run the tests on local disk space
  • --basename=BASENAME — Base name for all files and logs [default: automatically generated]
  • --nfsdebug=NFSDEBUG — Set NFS kernel debug flags and save log messages [default: '']
  • --rpcdebug=RPCDEBUG — Set RPC kernel debug flags and save log messages [default: '']
  • --tracepoints=TRACEPOINTS — List of trace points modules to enable [default: '']
  • --nfsstats — Get NFS stats [default: 'False']
  • --pktdisp — Display main packets related to the given test
  • --nfserrors — Fail every NFS error found in the packet trace
  • --client-ipaddr=CLIENT_IPADDR — IP address of localhost

👑 Reporting options:

  • --xunit-report — Generate xUnit compatible test report
  • --xunit-report-file=XUNIT_REPORT_FILE — Path to xout report file

🔥 Test options:

  • --runtest=RUNTEST — Comma separated list of tests to run, if list starts with a '^' then all tests are run except the ones listed [default: 'all']
  • --free-blocks=FREE_BLOCKS — Number of free blocks to use when trying to allocate all available space [default: 64]
  • --perf-fsize=PERF_FSIZE — Starting file size for the perf01 test [default: 1MB]
  • --perf-mult=PERF_MULT — File size multiplier for the perf01 test, the tests are performed for a file size which is a multiple of the previous test file size [default: 4]
  • --perf-time=PERF_TIME — Run the performance test perf01 until the sub-test for the current file size executes for more than this time [default: 15]

💫 TESTS 💫

alloc

Run all ALLOCATE tests: alloc01, alloc02, alloc03, alloc04, alloc05, alloc06

alloc01

Verify ALLOCATE succeeds on files opened as write only

alloc02

Verify ALLOCATE succeeds on files opened as read and write

alloc03

Verify ALLOCATE fails on files opened as read only

alloc04

Verify ALLOCATE fails with EINVAL for invalid offset or length

alloc05

Verify ALLOCATE fails with ESPIPE when using a named pipe file handle

alloc06

Verify ALLOCATE reserves the disk space

dealloc

Run all DEALLOCATE tests: dealloc01, dealloc02, dealloc03, dealloc04, dealloc05, dealloc06

dealloc01

Verify DEALLOCATE succeeds on files opened as write only

dealloc02

Verify DEALLOCATE succeeds on files opened as read and write

dealloc03

Verify DEALLOCATE fails on files opened as read only

dealloc04

Verify DEALLOCATE fails with EINVAL for invalid offset or length

dealloc05

Verify DEALLOCATE fails with ESPIPE when using a named pipe file handle

dealloc06

Verify DEALLOCATE unreserves the disk space

perf01

Verify ALLOCATE outperforms initializing the file to all zeros

all

Run all tests: alloc01, alloc02, alloc03, alloc04, alloc05, alloc06, dealloc01, dealloc02, dealloc03, dealloc04, dealloc05, dealloc06, perf01

🌟 EXAMPLES 🌟

the only required option is --server, bestie. that's it. that's the whole requirement 🫶

$ nfstest_alloc --server 192.168.0.11

⭐ NOTES ⭐

  • the user id in the local host must have access to run commands as root using the 'sudo' command without the need for a password.
  • tests which require filling up all the disk space on the mounted device should have exclusive access to the device.
  • Valid only for NFS version 4.2 and above.
no seriously, the exclusive access thing is not a suggestion. do not share the device while these tests are running, it's giving chaos 🙈

🌈 SEE ALSO 🌈

formatstr(3), nfstest.test_util(3), nfstest.utils(3), nfstest_cache(1), nfstest_delegation(1), nfstest_dio(1), nfstest_fcmp(1), nfstest_file(1), nfstest_interop(1), nfstest_io(1), nfstest_lock(1), nfstest_pkt(1), nfstest_pnfs(1), nfstest_posix(1), nfstest_rdma(1), nfstest_sparse(1), nfstest_ssc(1), nfstest_xattr(1), nfstest_xid(1), packet.nfs.nfs4_const(3)

💀 BUGS 💀

No known bugs. (iconic behavior honestly, we love a clean bug section ✨)

💖 AUTHOR 💖

Jorge Mora (mora@netapp.com)

and that's the whole page bestie!! 🎀 this was NFStest 3.2, dated 21 March 2023, from the nfstest_alloc 1.3 era — go reserve some space, periodt. 💅🦋

📦 where this page comes from