nfstest_alloc man page

nfstest_alloc — Space reservation tests

Synopsis

nfstest_alloc --server <server> [options]

Description

Verify correct functionality of space reservations so applications are able to reserve or unreserve space for a file. The system call fallocate is used to manipulate the allocated disk space for a file, either to preallocate or deallocate it. For filesystems which support the fallocate system call, preallocation is done quickly by allocating blocks and marking them as uninitialized, requiring no I/O to the data blocks. This is much faster than creating a file and filling it with zeros.

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 make sure data can be written to the allocated range without any problems. Also, any data written outside the allocated range will fail with NFS4ERR_NOSPC when there is no more space left on the device. On the other hand, deallocating space will give the disk space back so it can be used by either the same file on regions not already preallocated or by different files without the risk of getting a no space error.

Performance testing using ALLOCATE versus initializing a file to all zeros is also included. The performance comparison is done with different file sizes.

Some tests include testing at the protocol level by taking a packet trace and inspecting the actual packets sent to the server or servers.

Negative testing is included whenever possible since some testing cannot be done at the protocol level because 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 is 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']
-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: 'none']
--tverbose=TVERBOSE
Verbose level for test messages [default: '1']
--createlog
Create log file
--warnings
Display warnings
--tag=TAG
Informational tag, it is displayed as an INFO message [default: '']

Packet trace options

--createtraces
Create a packet trace for each test
--tbsize=TBSIZE
Capture buffer size for tcpdump [default: '50000']
--trcdelay=TRCDELAY
Seconds to delay before stopping packet trace [default: 0.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: 65536]
--rsize=RSIZE
Read size to use when reading files [default: 4096]
--wsize=WSIZE
Write size to use when writing files [default: 4096]
--iodelay=IODELAY
Seconds to delay I/O operations [default: 0.1]
--offset-delta=OFFSET_DELTA
Read/Write offset delta [default: 4096]

Path options

--sudo=SUDO
Full path of binary for sudo [default: '/usr/bin/sudo']
--tcpdump=TCPDUMP
Full path of binary for tcpdump [default: '/usr/sbin/tcpdump']
--iptables=IPTABLES
Full path of binary for iptables [default: '/sbin/iptables']
--messages=MESSAGES
Full path of log messages file [default: '/var/log/messages']
--tmpdir=TMPDIR
Temporary directory [default: '/tmp']

Debug options

--nocleanup
Do not cleanup created files
--bugmsgs=BUGMSGS
File containing test messages to mark as bugs if they failed
--ignore
Ignore all bugs given by bugmsgs
--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: '']

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']
--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

Examples

The only required option is --server
$ 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.

See Also

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

Bugs

No known bugs.

Author

Jorge Mora (mora@netapp.com)

Referenced By

nfstest(1), nfstest_cache(1), nfstest_delegation(1), nfstest_dio(1), nfstest_file(1), nfstest_interop(1), nfstest_io(1), nfstest_lock(1), nfstest_pkt(1), nfstest_pnfs(1), nfstest_posix(1), nfstest_sparse(1), nfstest_xid(1).

23 November 2015 NFStest 2.1.1 nfstest_alloc 1.0