.\" DO NOT MODIFY THIS FILE!  It was generated by setup.py 1.2.
.TH NFSTEST_SSC 1 "21 March 2023" "NFStest 3.2" "nfstest_ssc 1.2"
.SH NAME
nfstest_ssc - Server side copy tests
.SH SYNOPSIS
nfstest_ssc --server <server> [options]
.SH DESCRIPTION
Verify correct functionality of server side copy

Copying a file via NFS the client reads the data from the source file and
then writes the same data to the destination file which is located in the
same server or it could be located in a different server. Either way the
file data is transferred twice, once for reading and the second for writing.
Server side copy allows unnecessary network traffic to be eliminated.
The intra-server copy allows the client to request the server to perform
the copy internally thus avoiding any data being sent through the network
at all. In the case for the inter-server copy where the destination server
is different from the source server, the client authorizes both servers
to interact directly with one another.

The system call copy_file_range is used to send both intra and inter
server side copy requests to the correct server.

Basic server side copy tests verify the actual file range from the source
file(s) are copied correctly to the destination file(s). Most tests deal
with a single source and destination file while verifying the data is copied
correctly. Also it verifies the data is copied starting from the correct
source offset and it is copied to the correct offset on the destination file.
Other tests deal with multiple files: 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.

Some tests include testing at the protocol level by taking a packet trace
and inspecting 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 to authorize the source server to allow the destination
server to copy the data directly; then the client sends the COPY operation
to the destination server so it could initiate the actual copy.

The server side copy could either be synchronous or asynchronous depending
on both client and server(s). The client could issue either a synchronous
or asynchronous copy and the server could either copy the file data in either
mode depending on implementation or other factors. In either case, the tests
verify the correct functionality for both cases. The CB_OFFLOAD operation is
used by the destination server to report the actual results of the copy when
it is done. The client could also actively query the destination server for
status on a current asynchronous copy using the OFFLOAD_STATUS operation.
Also the client has a mechanism to cancel a given asynchronous copy using
the OFFLOAD_CANCEL operation.

Negative testing is included whenever possible since some testing cannot be
done at the protocol level because 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 letting the server deal with the
error. 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 is a non-regular file type.


.SH OPTIONS
.IP "--version"
show program's version number and exit
.IP "-h, --help"
show this help message and exit
.IP "-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

.SS NFS specific options:

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

.SS Logging options:

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

.SS Packet trace options:

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

.SS File options:

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

.SS Path options:

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

.SS Debug options:

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

.SS Reporting options:

.IP "--xunit-report"
Generate xUnit compatible test report
.IP "--xunit-report-file=XUNIT_REPORT_FILE"
Path to xout report file

.SS Test options:

.IP "--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']
.IP "--dst-server=DST_SERVER"
Destination server for inter server side copy [default: none]
.IP "--dst-export=DST_EXPORT"
Destination export for inter server side copy [default: none]
.IP "--ncopies=NCOPIES"
Number of concurrent copies to use on intra14 and inter14 tests
[default: 4]
.IP "--src-files=SRC_FILES"
Number of source files to use concurrently on intra15 and inter15
tests [default: 3]
.IP "--dst-files=DST_FILES"
Number of destination files to use concurrently on intra15 and
inter15 tests [default: 2]
.IP "--pre-write=PRE_WRITE"
Write destination file before copy_file_range [default: 1]
.IP "--locks=LOCKS"
Lock files [default: 1]
.SH TESTS
.SS intra
.nf
Run all intra server side copy tests: intra01, intra02, intra03,
intra04, intra05, intra06, intra07, intra08, intra09, intra10, intra11,
intra12, intra13, intra14, intra15
.fi
.SS pintra
.nf
Run all positive intra server side copy tests: intra01, intra02,
intra03, intra04, intra05, intra06, intra07, intra08, intra14, intra15
.fi
.SS nintra
.nf
Run all negative intra server side copy tests: intra09, intra10,
intra11, intra12, intra13
.fi
.SS intra01
.nf
Verify intra server side COPY succeeds
.fi
.SS intra02
.nf
Verify intra server side COPY succeeds when using source offset
.fi
.SS intra03
.nf
Verify intra server side COPY succeeds when using destination offset
.fi
.SS intra04
.nf
Verify intra server side COPY succeeds when using NULL as source offset
.fi
.SS intra05
.nf
Verify intra server side COPY succeeds when using NULL as destination
offset
.fi
.SS intra06
.nf
Verify intra server side COPY succeeds when using count = 0
.fi
.SS intra07
.nf
Verify intra server side COPY succeeds when the source file is opened
as read/write
.fi
.SS intra08
.nf
Verify intra server side COPY succeeds when the destination file is
opened as read/write
.fi
.SS intra09
.nf
Verify intra server side COPY fails when the source file is opened
as write only
.fi
.SS intra10
.nf
Verify intra server side COPY fails when the destination file is opened
as read only
.fi
.SS intra11
.nf
Verify intra server side COPY succeeds when source offset is beyond the
end of the file
.fi
.SS intra12
.nf
Verify intra server side COPY succeeds when source offset plus count
is beyond the end of the file
.fi
.SS intra13
.nf
Verify intra server side COPY may fail when both source and destination
files point to the same file
.fi
.SS intra14
.nf
Verify intra server side COPY succeeds when using multiple source and
destination offsets
.fi
.SS intra15
.nf
Verify intra server side COPY succeeds when using multiple source and
destination files
.fi
.SS inter
.nf
Run all inter server side copy tests: inter01, inter02, inter03,
inter04, inter05, inter06, inter07, inter08, inter09, inter10, inter11,
inter12, inter13, inter14, inter15
.fi
.SS pinter
.nf
Run all positive inter server side copy tests: inter01, inter02,
inter03, inter04, inter05, inter06, inter07, inter08, inter13, inter14,
inter15
.fi
.SS ninter
.nf
Run all negative inter server side copy tests: inter09, inter10,
inter11, inter12
.fi
.SS inter01
.nf
Verify inter server side COPY succeeds
.fi
.SS inter02
.nf
Verify inter server side COPY succeeds when using source offset
.fi
.SS inter03
.nf
Verify inter server side COPY succeeds when using destination offset
.fi
.SS inter04
.nf
Verify inter server side COPY succeeds when using NULL as source offset
.fi
.SS inter05
.nf
Verify inter server side COPY succeeds when using NULL as destination
offset
.fi
.SS inter06
.nf
Verify inter server side COPY succeeds when using count = 0
.fi
.SS inter07
.nf
Verify inter server side COPY succeeds when the source file is opened
as read/write
.fi
.SS inter08
.nf
Verify inter server side COPY succeeds when the destination file is
opened as read/write
.fi
.SS inter09
.nf
Verify inter server side COPY fails when the source file is opened
as write only
.fi
.SS inter10
.nf
Verify inter server side COPY fails when the destination file is opened
as read only
.fi
.SS inter11
.nf
Verify inter server side COPY succeeds when source offset is beyond the
end of the file
.fi
.SS inter12
.nf
Verify inter server side COPY succeeds when source offset plus count
is beyond the end of the file
.fi
.SS inter13
.nf
Verify inter server side COPY succeeds when both source and destination
file names are the same
.fi
.SS inter14
.nf
Verify inter server side COPY succeeds when using multiple source and
destination offsets
.fi
.SS inter15
.nf
Verify inter server side COPY succeeds when using multiple source and
destination files
.fi
.SS positive
.nf
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
.fi
.SS negative
.nf
Run all negative server side copy tests: intra09, intra10, intra11,
intra12, intra13, inter09, inter10, inter11, inter12
.fi
.SS all
.nf
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
.fi
.SH EXAMPLES
The only required option is --server
.br
$ nfstest_ssc --server 192.168.0.11
.SH NOTES
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.

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

Valid only for NFS version 4.2 and above.
.SH SEE ALSO
.BR baseobj(3),
.BR formatstr(3),
.BR nfstest.test_util(3),
.BR nfstest_alloc(1),
.BR nfstest_cache(1),
.BR nfstest_delegation(1),
.BR nfstest_dio(1),
.BR nfstest_fcmp(1),
.BR nfstest_file(1),
.BR nfstest_interop(1),
.BR nfstest_io(1),
.BR nfstest_lock(1),
.BR nfstest_pkt(1),
.BR nfstest_pnfs(1),
.BR nfstest_posix(1),
.BR nfstest_rdma(1),
.BR nfstest_sparse(1),
.BR nfstest_xattr(1),
.BR nfstest_xid(1),
.BR packet.nfs.nfs3_const(3),
.BR packet.nfs.nfs4_const(3)

.SH BUGS
No known bugs.
.SH AUTHOR
Jorge Mora (mora@netapp.com)