NFSTEST_SSC(1)

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

🌸 NAME 🌸

nfstest_ssc — server side copy tests 💖

(you're reading the manual page for nfstest_ssc, version 1.2, section 1 of the manual — welcome bestie 🫶)

✨ SYNOPSIS ✨

nfstest_ssc --server <server> [options]

🦋 DESCRIPTION 🦋

Okay so the whole vibe here is: verify correct functionality of server side copy. That's it, that's the mission. 💅

Let's set the scene, because it's giving "why do we even need this". When you copy a file over NFS the normal way, the client reads the data out of the source file and then writes that exact same data into the destination file. And the destination file can live on the same server, or it can live on a totally different server. Either way? The file data gets transferred twice — once for the read, once for the write. So much wasted motion, no cap. 😭

Server side copy is the glow-up that kills all that unnecessary network traffic. For an intra-server copy, the client just asks the server to do the copy <em>internally</em>, so literally no data goes over the network at all. Obsessed. And for the inter-server copy, where the destination server is a different server from the source server, the client authorizes both servers to interact <em>directly with each other</em> — they talk amongst themselves, main character energy, and the client is just the matchmaker. 🧚

The system call copy_file_range is what sends both the intra and the inter server side copy requests to the correct server. Iconic syscall, honestly.

So what do the basic server side copy tests actually check? They verify the actual file range from the source file(s) is copied correctly into the destination file(s). Most tests deal with a single source and a single destination file while checking the data landed right. They also verify the data is copied starting from the correct source offset and that it lands on the correct offset in the destination file. Then there are the multi-file tests: copying multiple source files to a single destination file, a single source file to multiple destination files, or N number of source files to M number of destination files. Chaos, but organized chaos. 🌈

Some tests go full protocol-level detective mode 🔍 — they take a packet trace and inspect the actual packets sent to the server (or servers).

  • For the intra-server side copy, these tests verify the COPY/CLONE operation is sent to the server with correct arguments.
  • For the inter-server side copy, these tests verify the COPY_NOTIFY operation is sent to the source server with correct arguments, authorizing the source server to let the destination server copy the data directly. Then the client sends the COPY operation to the destination server so it can initiate the actual copy.

Now, the copy itself could be synchronous or asynchronous depending on both the client and the server(s) — the client can issue either, and the server can copy the file data in either mode depending on its implementation or other factors. Either way, the tests verify correct functionality for both cases. 💀

  • The CB_OFFLOAD operation is used by the destination server to report the actual results of the copy once it's done.
  • The client can also actively query the destination server for status on a current asynchronous copy using the OFFLOAD_STATUS operation.
  • And the client has a mechanism to cancel a given asynchronous copy using the OFFLOAD_CANCEL operation.

Negative testing is included whenever possible, because some testing just can't be done at the protocol level — the copy_file_range system call does some error checking of its own, and the NFS client won't even send a COPY_NOTIFY or COPY operation to the server, so the server never even gets to deal with the error. Rude, but okay. 🙈 The negative tests include:

  • trying to copy an invalid source range
  • having an invalid value for either the offset or the length
  • trying to copy a region on a source file opened as write only
  • a destination 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, the user wide file $HOME/.nfstest, or the .nfstest file in the current directory

🌟 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; the 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: 256k]
  • --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 the list starts with a '^' then all tests are run <em>except</em> the ones listed [default: 'all']
  • --dst-server=DST_SERVER — Destination server for inter server side copy [default: none]
  • --dst-export=DST_EXPORT — Destination export for inter server side copy [default: none]
  • --ncopies=NCOPIES — Number of concurrent copies to use on intra14 and inter14 tests [default: 4]
  • --src-files=SRC_FILES — Number of source files to use concurrently on intra15 and inter15 tests [default: 3]
  • --dst-files=DST_FILES — Number of destination files to use concurrently on intra15 and inter15 tests [default: 2]
  • --pre-write=PRE_WRITE — Write destination file before copy_file_range [default: 1]
  • --locks=LOCKS — Lock files [default: 1]

and that's only part one bestie, don't go anywhere — there's more coming 💖✨

✨ TESTS ✨

okay so this is the part where you pick your fighter. Each one is a test name you can run, and the group names are like playlists that run a bunch of them together. No cap. 💅

🧪 intra

Run all intra server side copy tests: intra01, intra02, intra03, intra04, intra05, intra06, intra07, intra08, intra09, intra10, intra11, intra12, intra13, intra14, intra15

That's the whole intra squad, bestie. ✨

🎀 pintra

Run all positive intra server side copy tests: intra01, intra02, intra03, intra04, intra05, intra06, intra07, intra08, intra14, intra15

All the good vibes only. No failures allowed here. 💖

💀 nintra

Run all negative intra server side copy tests: intra09, intra10, intra11, intra12, intra13

The chaotic ones. They're supposed to fail, and that's iconic. 😭

intra01

Check it: intra server side COPY succeeds. That's it. That's the test. 💅

intra02

Check it: intra server side COPY succeeds when using source offset. Offset queen behavior. 👑

intra03

Check it: intra server side COPY succeeds when using destination offset. Destination offset, but make it fashion. 🎀

intra04

Check it: intra server side COPY succeeds when using NULL as source offset. NULL is valid here, no cap. 🙈

intra05

Check it: intra server side COPY succeeds when using NULL as destination offset. Again NULL, again iconic. 💖

intra06

Check it: intra server side COPY succeeds when using count = 0. Zero count, zero problems. 🔥

intra07

Check it: intra server side COPY succeeds when the source file is opened as read/write. Source file read/write, periodt. 👑

intra08

Check it: intra server side COPY succeeds when the destination file is opened as read/write. Destination file read/write, slay. 💅

intra09

Check it: intra server side COPY fails when the source file is opened as write only. Write-only source means failure, and that's correct. 💀

intra10

Check it: intra server side COPY fails when the destination file is opened as read only. Read-only destination means failure, as intended. 🚫

intra11

Check it: intra server side COPY succeeds when source offset is beyond the end of the file. Offset past EOF, still succeeding. 🌈

intra12

Check it: intra server side COPY succeeds when source offset plus count is beyond the end of the file. Offset plus count past EOF, still eating. 🍓

intra13

Check it: intra server side COPY may fail when both source and destination files point to the same file. May fail, bestie. Not a guarantee. 😭

intra14

Check it: intra server side COPY succeeds when using multiple source and destination offsets. Multiple offsets, multiple wins. ✨

intra15

Check it: intra server side COPY succeeds when using multiple source and destination files. Multiple files, main character energy. 👑

🌸 inter

Run all inter server side copy tests: inter01, inter02, inter03, inter04, inter05, inter06, inter07, inter08, inter09, inter10, inter11, inter12, inter13, inter14, inter15

The inter server side copy squad, assembled. 🫶

💖 pinter

Run all positive inter server side copy tests: inter01, inter02, inter03, inter04, inter05, inter06, inter07, inter08, inter13, inter14, inter15

Positive only, no negativity allowed. ✨

💀 ninter

Run all negative inter server side copy tests: inter09, inter10, inter11, inter12

Negative tests, but make it dramatic. They should fail. Periodt. 😭

inter01

Check it: inter server side COPY succeeds. Success is the vibe. ✅

inter02

Check it: inter server side COPY succeeds when using source offset. Source offset, but inter. Slay. 💅

inter03

Check it: inter server side COPY succeeds when using destination offset. Destination offset, inter edition. 🎀

inter04

Check it: inter server side COPY succeeds when using NULL as source offset. NULL source offset? Valid and cute. 💖

inter05

Check it: inter server side COPY succeeds when using NULL as destination offset. NULL destination offset, still serving. 🫶

inter06

Check it: inter server side COPY succeeds when using count = 0. count = 0, but make it succeed. 🔥

inter07

Check it: inter server side COPY succeeds when the source file is opened as read/write. Read/write source, no notes. 👑

inter08

Check it: inter server side COPY succeeds when the destination file is opened as read/write. Read/write destination, iconic. 💅

inter09

Check it: inter server side COPY fails when the source file is opened as write only. Write-only source, instant fail. And that's correct. 💀

inter10

Check it: inter server side COPY fails when the destination file is opened as read only. Read-only destination, nope, fail. As intended. 🚫

inter11

Check it: inter server side COPY succeeds when source offset is beyond the end of the file. Source offset past EOF, still eating. 🌈

inter12

Check it: inter server side COPY succeeds when source offset plus count is beyond the end of the file. Offset plus count beyond EOF, still slaying. 🍓

inter13

Check it: inter server side COPY succeeds when both source and destination file names are the same. Same file names, still succeeding. No cap. ✨

inter14

Check it: inter server side COPY succeeds when using multiple source and destination offsets. Multiple offsets, multiple wins. 👑

inter15

Check it: inter server side COPY succeeds when using multiple source and destination files. Multiple files, inter style. 🫶

🌟 positive

Run all positive server side copy tests: intra01, intra02, intra03, intra04, intra05, intra06, intra07, intra08, intra14, intra15, inter01, inter02, inter03, inter04, inter05, inter06, inter07, inter08, inter13, inter14, inter15

All the positive ones, combined. It's giving sunshine. ☀️

💀 negative

Run all negative server side copy tests: intra09, intra10, intra11, intra12, intra13, inter09, inter10, inter11, inter12

All the negative ones, combined. They're supposed to fail, and they do it beautifully. 😭

👑 all

Run all tests: intra01, intra02, intra03, intra04, intra05, intra06, intra07, intra08, intra09, intra10, intra11, intra12, intra13, intra14, intra15, inter01, inter02, inter03, inter04, inter05, inter06, inter07, inter08, inter09, inter10, inter11, inter12, inter13, inter14, inter15

Every single test. The whole buffet. Main character energy only. 💅

💖 EXAMPLES 💖

The only required option is --server. That's it, bestie.

$ nfstest_ssc --server 192.168.0.11

📝 NOTES 📝

okay so notes time. 📝

The user id in the local host and the host specified by --dst-server must have access to run commands as root using the 'sudo' command without the need for a password. No password prompts, periodt.

The user id must be able to 'ssh' to remote host without the need for a password. Passwordless ssh or bust. 🫶

Valid only for NFS version 4.2 and above. So if you're on anything lower, this is not it. 💀

👀 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_lock(1), nfstest_pkt(1), nfstest_pnfs(1), nfstest_posix(1), nfstest_rdma(1), nfstest_sparse(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)

okay bye bestie, this page was brought to you by NFStest 3.2, dated 21 March 2023, and it's the NFSTEST_SSC(1) manual. Go run some tests and slay. 💖✨

📦 where this page comes from