NFSTEST_LOCK(1)

💖 NFSTEST_LOCK 💖

okay bestie, welcome to nfstest_lock — it's the nfstest_lock 1.3 tool, manual section 1, and it's literally the moment your NFS locking setup gets a full glow-up. grab a snack, this one's a long one but we're doing it together 🫶

---

✨ NAME ✨

nfstest_lock — locking tests 🔒

---

🌸 SYNOPSIS 🌸

nfstest_lock --server <server> [--client <client>] [options]

---

🦋 DESCRIPTION 🦋

so the basic locking tests are like... the vibe check for whether a lock actually gets granted when you throw different arguments at fcntl. we're talking blocking locks and non-blocking locks, read locks and write locks, and the file gets opened for reading, writing, or both — all the combos. it also pokes at different ranges, including the limit conditions, because edge cases are where the drama lives 😭

then the non-overlapping tests make sure locks get granted on both the client under test and a second process or a remote client when they're locking the same file. everybody eats, no conflict, iconic 💅

and the overlapping tests?? that's where it gets spicy 🔥 a lock gets granted on the client under test, and meanwhile a second process or remote client tries to lock the same file — and they get denied if they issued a non-blocking lock, or blocked if they issued a blocking lock. no cap, that's the whole point.

---

👑 OPTIONS 👑

the basics, the little starter pack:

• --version — shows the program's version number and dips ✨
• -h, --help — shows this help message and dips ✨
• *-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 stuff, periodt:

• *-s *SERVER, --server=SERVER — server name or IP address 📡
• *-e *EXPORT, --export=EXPORT — exported file system to mount [default: '/']
• *--nfsversion=NFSVERSION* — NFS version, like 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 gets created on the mount point [default: '']

💜 Logging options 💜

for when you want receipts 📝:

• *-v *VERBOSE, --verbose=VERBOSE — verbose level for debug messages [default: 'opts|info|dbg1|dbg2|dbg3']
• *--tverbose=TVERBOSE* — verbose level for test messages [default: '2']
• --createlog — create log file
• --rexeclog — create rexec log files
• --warnings — display warnings ⚠️
• *--tag=TAG* — informational tag, displayed as an INFO message [default: '']
• --notty — do not use terminal colors on output
• --isatty — use terminal colors on output — lowkey useful when running with nohup 🎀

🍓 Packet trace options 🍓

for the girls who love packet forensics:

• --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]
• --subtraces — create a packet trace for each sub-test. > bestie, use this with caution because it will create a lot of packet traces 💀 use --createtraces instead unless you're trying to get a packet trace for one specific sub-test. it's best in combination with the --runtest option.

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

where all your little binaries live:

• *--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 💅

main character debugging energy:

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

this is the good part, buckle up:

• *--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']
• *--client=CLIENT* — remote NFS client and options used for conflicting lock tests. clients are separated by a ',' and each client definition is a list of arguments separated by a ':' given in the following order if positional arguments is used (see examples): clientname:server:export:nfsversion:port:proto:sec:mtpoint
• *--nfsopts=NFSOPTS* — local process NFS options used for conflicting lock tests. processes are separated by a ',' and each process definition is a list of arguments separated by a ':' given in the following order if positional arguments is used (see examples): :server:export:nfsversion:port:proto:sec:mtpoint
• *--offset=OFFSET* — offset of first lock granted [default: 4k]
• *--length=LENGTH* — length of first lock granted [default: 4k]
• *--unlock-delay=UNLOCK_DELAY* — time in seconds to unlock first lock [default: 2.0]
• *--lockw-timeout=LOCKW_TIMEOUT* — time in seconds to wait for blocked lock after conflicting lock has been released [default: 30]
• *--opentype=OPENTYPE* — list of open types to test [default: read,write,rdwr]
• *--locktype=LOCKTYPE* — list of lock types to test [default: read,write]
• *--opentype2=OPENTYPE2* — list of open types to test on remote client [default: read,write,rdwr]
• *--locktype2=LOCKTYPE2* — list of lock types to test on remote client [default: read,write]
• *--setlock=SETLOCK* — list of set lock types to test [default: immediate,block]

✨ TESTS ✨

okay bestie, here's the whole test menu 💖 each one is checking a different locking vibe, and you're gonna slay every single one.

---

btest01

Basic locking tests 🎀

These tests verify that a lock is granted using various arguments to fcntl. That includes blocking and non-blocking locks, read or write locks, and the file being opened for reading, writing, or both. It also checks different ranges, including limit conditions.

noverlap

Run all the non-overlapping locking tests: nptest01, nptest02, nptest03, nptest04, nctest01, nctest02, nctest03, nctest04

nptest

Run all non-overlapping locking tests using a second process: nptest01, nptest02, nptest03, nptest04

nptest01

Locking non-overlapping range from a second process where end2 < start1

process1:                     |------------------|
process2: |--------|

nptest02

Locking non-overlapping range from a second process where end2 == start1 - 1

process1:                     |------------------|
process2: |------------------|

nptest03

Locking non-overlapping range from a second process where start2 > end1

process1: |------------------|
process2:                               |--------|

nptest04

Locking non-overlapping range from a second process where start2 == end1 + 1

process1: |------------------|
process2:                     |------------------|

nctest

Run all non-overlapping locking tests using a second client: nctest01, nctest02, nctest03, nctest04

nctest01

Locking non-overlapping range from a second client where end2 < start1

client1:                      |------------------|
client2:  |--------|

nctest02

Locking non-overlapping range from a second client where end2 == start1 - 1

client1:                      |------------------|
client2:  |------------------|

nctest03

Locking non-overlapping range from a second client where start2 > end1

client1:  |------------------|
client2:                                |--------|

nctest04

Locking non-overlapping range from a second client where start2 == end1 + 1

client1:  |------------------|
client2:                      |------------------|

overlap

Run all overlapping locking tests: optest01, optest02, optest03, optest04, optest05, optest06, optest07, optest08, optest09, octest01, octest02, octest03, octest04, octest05, octest06, octest07, octest08, octest09

optest

Run all overlapping locking tests using a second process: optest01, optest02, optest03, optest04, optest05, optest06, optest07, optest08, optest09

optest01

Locking same range from a second process

process1:                     |------------------|
process2:                     |------------------|

optest02

Locking overlapping range from a second process where start2 < start1

process1:                     |------------------|
process2:           |------------------|

optest03

Locking overlapping range from a second process where end2 > end1

process1:                     |------------------|
process2:                               |------------------|

optest04

Locking overlapping range from a second process where range2 is entirely within range1

process1:                     |------------------|
process2:                          |--------|

optest05

Locking overlapping range from a second process where range1 is entirely within range2

process1:                     |------------------|
process2:                |----------------------------|

optest06

Locking full file range from a second process

optest07

Locking overlapping range from a second process where end2 == start1

process1:                     |------------------|
process2:  |------------------|

optest08

Locking overlapping range from a second process where start2 == end1

process1:  |------------------|
process2:                     |------------------|

optest09

Locking overlapping range from multiple processes where range2 and range3 are entirely within range1

  process1:                     |-----------------------------|
  process2:                          |--------|
  process3:                                    |--------|

octest

Run all overlapping locking tests using a second client: octest01, octest02, octest03, octest04, octest05, octest06, octest07, octest08, octest09

octest01

Locking same range from a second client

client1:                      |------------------|
client2:                      |------------------|

octest02

Locking overlapping range from a second client where start2 < start1

client1:                      |------------------|
client2:            |------------------|

octest03

Locking overlapping range from a second client where end2 > end1

client1:                      |------------------|
client2:                                |------------------|

octest04

Locking overlapping range from a second client where range2 is entirely within range1

client1:                      |------------------|
client2:                           |--------|

octest05

Locking overlapping range from a second client where range1 is entirely within range2

client1:                      |------------------|
client2:                 |----------------------------|

octest06

Locking full file range from a second client

octest07

Locking overlapping range from a second client where end2 == start1

client1:                      |------------------|
client2:   |------------------|

octest08

Locking overlapping range from a second client where start2 == end1

client1:   |------------------|
client2:                      |------------------|

octest09

Locking overlapping range from multiple clients where range2 and range3 are entirely within range1

  client1:                     |-----------------------------|
  client2:                          |--------|
  client3:                                    |--------|

all

Run all tests: btest01, nptest01, nptest02, nptest03, nptest04, nctest01, nctest02, nctest03, nctest04, optest01, optest02, optest03, optest04, optest05, optest06, optest07, optest08, optest09, octest01, octest02, octest03, octest04, octest05, octest06, octest07, octest08, octest09

---

🌈 EXAMPLES 🌈

Run the tests which use only the main client (no --client option):

nfstest_lock --server 192.168.0.2 --export /exports

Use short options instead:

nfstest_lock -s 192.168.0.2 -e /exports

Use positional arguments with nfsversion=3 for extra client:

nfstest_lock -s 192.168.0.2 -e /exports --client 192.168.0.10:::3

Use named arguments instead:

nfstest_lock -s 192.168.0.2 -e /exports --client 192.168.0.10:nfsversion=3

Use positional arguments with nfsversion=3 for second process:

nfstest_lock -s 192.168.0.2 -e /exports --nfsopts :::3

Use named arguments instead:

nfstest_lock -s 192.168.0.2 -e /exports --nfsopts nfsversion=3

---

💌 NOTES 💌

The user id in the local host and the host specified by --client must have access to run commands as root using the sudo command without the need for a password.

The user id must be able to ssh to remote host without the need for a password.

---

👀 SEE ALSO 👀

• baseobj(3)
• formatstr(3)
• 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_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.nfs3_const(3)
• packet.nfs.nfs4_const(3)
• packet.nfs.nlm4_const(3)

---

💀 BUGS 💀

No known bugs. periodt 💅

---

👑 AUTHOR 👑

Jorge Mora (mora@netapp.com)

---

This iconic page is from NFStest 3.2, dated 21 March 2023, and it's the NFSTEST_LOCK(1) manual. slay, bestie 💖✨