NFSTEST_POSIX(1)

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

✨ NFSTEST_POSIX ✨

okay bestie, welcome to nfstest_posix — this is the 1.2 era of the page and it's giving thorough. it's the POSIX file system level access test suite and she does NOT skip leg day. 🦋

🌸 NAME 🌸

nfstest_posix — POSIX file system level access tests 💅

🎀 SYNOPSIS 🎀

nfstest_posix --server <server> [options]

💖 DESCRIPTION 💖

So what she does is verify POSIX file system level access over the path you give her, using positive and negative testing. like she tests the good path AND the "what happens if you do this cursed thing" path. icon behavior honestly.

Valid for any version of NFS. every single one. she doesn't play favorites. ✨

👑 OPTIONS 👑

the main character section. buckle up.

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

🌈 NFS specific options 🌈

the NFS-flavored ones. iykyk.

  • -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.1]
  • -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; the directory is created on the mount point [default: '']

💜 Logging options 💜

receipts. we keep them.

  • -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 🦋

for when you need to see every little packet's business. nosy (affectionate).

  • --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 🍓

making files, reading files, writing files. the whole little family.

  • --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 🧚

where all the little binaries live. she needs to know their addresses fr fr.

  • --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 🔥

the "why is this happening to me" section. we've all been there.

  • --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 ⭐

for when you need to show the teacher your work.

  • --xunit-report — generate xUnit compatible test report
  • --xunit-report-file=XUNIT_REPORT_FILE — path to xout report file

🌸 Test options 🌸

the actual "what are we running today" of it all.

  • --runtest=RUNTEST — comma separated list of tests to run; if the list starts with a ^ then all tests are run except the ones listed [default: all]

and that's part one, bestie. more is coming, don't you dare close the tab 💖

✨ TESTS ✨

access 💅

okay so this one's literally just vibe-checking the POSIX API access() on files with different modes. no cap.

chdir 🦋

bestie we're testing chdir() by changing into a freshly made directory and then changing right back to where we started. it's giving homecoming.

close 🎀

this one checks that close() actually works, and that if you try to write to a file descriptor after closing it, you get an error. as you should 💀.

closedir ✨

just verifying that closedir() does its thing.

creat 🌸

so creat(path, mode) should be exactly equivalent to open(path, O_WRONLY|O_CREAT|O_TRUNC, mode). first we test with a path that doesn't exist yet to make sure the file gets created, then we test with a path that does exist to make sure it gets truncated. periodt.

fcntl 👑

this is the big one for the POSIX API fcntl(). we're checking these commands: F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, and FD_CLOEXEC.

  • F_DUPFD — we do operations on the original and the dupped file descriptor to make sure they both behave correctly.
  • F_GETFD and F_SETFD — we set the FD_CLOEXEC flag and make sure it actually gets set.
  • F_GETFL and F_SETFL — we set the O_APPEND flag and make sure it gets set.

and we run the whole test for both 'read' and 'write'. slay.

fdatasync 🔥

just making sure fdatasync() works.

fstat 💖

checking fstat() by looking at the mode on a file and making sure it returns the expected structure members. then we create a symlink and verify that fstat returns info about the link. iconic.

fstatvfs 🦋

verifying fstatvfs() by making sure all the members of the structure are returned. all of them. no missing pieces.

fsync ⭐

yep, just fsync(). making sure it works.

link(src, dst) should create a link and update the st_ctime field for the file. also verify that link updates the st_ctime and st_mtime for the directory. and verify that the st_link count gets incremented by 1 for the file. math is mathing.

lseek 🎀

testing lseek() with different offsets and whence values, including seeking past the end of the file. living on the edge.

lstat 💜

checking lstat() by looking at the mode on a file and making sure it returns the expected structure members. create a symlink and verify that lstat returns info about the link. (not the file it points to, bestie.)

mkdir 🌸

verifying mkdir(). also verify that mkdir with a path of a symbolic link fails. and verify that the st_ctime and st_mtime fields of the parent directory get updated. we love a timestamp refresh.

mmap 🔥

testing mmap() by mapping a file and verifying I/O operations. verify that mmap followed by a memory read of an existing file works. verify that mmap followed by a memory write to the file works. it's giving memory-mapped realness.

munmap ✨

mapping a file and then unmapping it. that's munmap().

opendir 🦋

just checking opendir() on a directory.

read 💅

testing read() by reading data from a file. verify that the st_atime of the file is updated after the read. verify that a read of 0 bytes returns 0. period.

readdir 🎀

verifying readdir() on a directory.

verify readlink() by reading a symbolic link.

rename 👑

testing rename() by renaming a file, a directory, and a symbolic link. also verify that a rename from a file to a symbolic link will cause the symbolic link to be removed. bye bye link.

rewinddir 💖

verifying rewinddir() on a directory.

rmdir 🌸

testing rmdir() by removing a directory. verify that the parent's st_ctime and st_mtime are updated. we love updated timestamps.

seekdir ⭐

verifying seekdir() on a directory.

stat 💜

checking stat() by looking at the mode on a file and making sure it returns the expected structure members. create a symlink and verify that stat returns info about the file. (the file it points to, bestie.)

statvfs 🔥

verifying statvfs() by making sure all the members of the structure are returned. all of them.

testing symlink() by creating a symbolic link and verifying that the file type is slnk. (yes, slnk.)

sync 🦋

just sync(). making sure it works.

telldir 🎀

verifying telldir() on a directory.

this one's a whole journey. first, unlink a file and verify that it was removed. verify that the st_ctime and st_mtime fields of the parent directory were updated. then unlink a symbolic link and verify that the symbolic link was removed but not the referenced file. then remove an opened file and verify that I/O still occurs to the file after the unlink, and that the file gets removed when the file is closed. finally, create a file and then hard link to it so the link count is greater than 1. unlink the hard file and verify that the st_ctime field is updated. ate.

write 🌈

testing write() by writing 0 bytes and verifying 0 is returned. then write a pattern to the file, seek +N, write another pattern, and close the file. open the file and read in both written patterns and verify that it's the correct pattern. read in the data from the hole in the file and verify that it is 0. hole check slay.

open 👑

this one is a whole checklist for open() on a file.

  • Verify file creation using the O_CREAT flag and verify the file mode is set to the specified value.
  • Verify the st_ctime and st_mtime are updated on the parent directory after the file was created.
  • Verify open on an existing file fails with the O_EXCL flag set.
  • Verify write succeeds and read fails if the file was opened with O_WRONLY.
  • Verify read succeeds and write fails if the file was opened with O_RDONLY.
  • Verify that all writes with O_APPEND set are to the end of the file.
  • Use O_DSYNC, O_RSYNC, and O_SYNC flags in open calls.
  • Verify file open with O_CREAT and O_TRUNC set will truncate an existing file.
  • Verify that it updates the file st_ctime and st_mtime.

chmod 💖

testing chmod() on a file and a directory by trying all valid combinations of modes. verify that the st_ctime is updated for both the file and directory.

all 🎀

run all the tests: access, chdir, close, closedir, creat, fcntl, fdatasync, fstat, fstatvfs, fsync, link, lseek, lstat, mkdir, mmap, munmap, opendir, read, readdir, readlink, rename, rewinddir, rmdir, seekdir, stat, statvfs, symlink, sync, telldir, unlink, write, open, chmod. that's the whole lineup.

✨ EXAMPLES ✨

the only required option is --server.

$ nfstest_posix --server 192.168.0.11

🌸 NOTES 🌸

the user id on the local host must have access to run commands as root using the 'sudo' command without needing a password. (so like, passwordless sudo, bestie.)

🦋 SEE ALSO 🦋

nfstest.test_util(3), nfstest_alloc(1), 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_rdma(1), nfstest_sparse(1), nfstest_ssc(1), nfstest_xattr(1), nfstest_xid(1), packet.nfs.nfs3_const(3), packet.nfs.nfs4_const(3)

💀 BUGS 💀

no known bugs. (we love a clean slate.)

💅 AUTHOR 💅

Jorge Mora (mora@netapp.com)

and that's the tea, bestie. this page is from NFStest 3.2, dated 21 March 2023. stay iconic. 🫶💖

📦 where this page comes from