wtsi-hgi/petardfs

Name: petardfs

Owner: Wellcome Trust Sanger Institute - Human Genetics Informatics

Description: PetardFS - a FUSE filessytem for injecting intentional errors (e.g. for testing)

Created: 2013-11-19 12:51:17.0

Updated: 2014-07-22 14:43:29.0

Pushed: 2014-07-22 15:10:50.0

Homepage: null

Size: 250

Language: C++

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

petardfs

PetardFS - a FUSE filessytem for injecting intentional errors (e.g. for testing)

Originally developed by Ben Martin (http://sourceforge.net/projects/witme/files/petardfs/0.0.2/).

With no configuration petardfs takes a base filesystem and exposes it through FUSE.

An XML configuration file is used to tell petardfs which files to report errors for and what error code to use.

For example, foo.txt can have an EIO error at bytes 34 to 37. There is explicit support for errors such as EAGAIN and EINTR where petardfs will only report such transient errors a nominated number of times, handy for testing applications support such IO conditions gracefully.

XML Configuration File

An example configuration file can be found within the source tree at: testsuite/sampledata/config-simple-filesystem-simple-error-in-read-file1.xml

A basic configuation might look like:

CTYPE petardfs-config [
TITY EPERM   "1">
TITY ENOENT   "2">
TITY ESRCH   "3">
TITY EINTR   "4">
TITY EIO   "5">
TITY ENXIO   "6">
TITY E2BIG   "7">
TITY ENOEXEC   "8">
TITY EBADF   "9">
TITY ECHILD  "10">
TITY EAGAIN  "11">
TITY ENOMEM  "12">
TITY EACCES  "13">
TITY EFAULT  "14">
TITY ENOTBLK  "15">
TITY EBUSY  "16">
TITY EEXIST  "17">
TITY EXDEV  "18">
TITY ENODEV  "19">
TITY ENOTDIR  "20">
TITY EISDIR  "21">
TITY EINVAL  "22">
TITY ENFILE  "23">
TITY EMFILE  "24">
TITY ENOTTY  "25">
TITY ETXTBSY  "26">
TITY EFBIG  "27">
TITY ENOSPC  "28">
TITY ESPIPE  "29">
TITY EROFS  "30">
TITY EMLINK  "31">
TITY EPIPE  "32">
TITY EDOM  "33">
TITY ERANGE  "34">

ardfs-config>
errors>
 <read>
   <error path="/read-eintr-10.txt">
     <n start-offset="1" end-offset="1" error-code="&EINTR;" times="10"/>
   </error>
   <error path="/read-eio.txt">
     <n start-offset="2" end-offset="2" error-code="&EIO;"/>
   </error>
 </read>
 <write>
   <error path="/write-eio.txt">
     <n start-offset="2" end-offset="2" error-code="&EIO;"/>
   </error>
 </write>
 <open>
   <error path="/open-eio.txt" error-code="&EIO;" />
 </open>
/errors>
tardfs-config>

The read, write, and open elements represent the filesystem operation on which the errors contained within should be injected. Some operations (e.g. read and write) require an n element within the error element to specify which error-code should be introduced at which ranges of bytes (from start-offset to end-offset), while others (e.g. open) do not require that and can have the error-code specified in the error element itself.

The full list of operations which are supported for error injection are: read, write, fsync, mkdir, symlink, unlink, rmdir, rename, link, chmod, chown, ftruncate, utime, and open.

The list of error codes supported should be given as XML entity declarations at the top of each XML file. The full list is given in the above example.

The path within each error element is relative to the mount point of the filesystem.

Usage Example

The following example tests whether the diff and cat programs handle the fatal EIO error by erroring out and the EINTR error by retrying or reporting the error.

dule add hgi/xerces-c/latest hgi/petardfs/latest
dir /tmp/petard-data
q 1 100000 > /tmp/petard-data/testfile-fatal
q 1 100000 > /tmp/petard-data/testfile-retry
dir /tmp/petard-mnt
ho '<!DOCTYPE petardfs-config [
TITY EPERM   "1">
TITY ENOENT   "2">
TITY ESRCH   "3">
TITY EINTR   "4">
TITY EIO   "5">
TITY ENXIO   "6">
TITY E2BIG   "7">
TITY ENOEXEC   "8">
TITY EBADF   "9">
TITY ECHILD  "10">
TITY EAGAIN  "11">
TITY ENOMEM  "12">
TITY EACCES  "13">
TITY EFAULT  "14">
TITY ENOTBLK  "15">
TITY EBUSY  "16">
TITY EEXIST  "17">
TITY EXDEV  "18">
TITY ENODEV  "19">
TITY ENOTDIR  "20">
TITY EISDIR  "21">
TITY EINVAL  "22">
TITY ENFILE  "23">
TITY EMFILE  "24">
TITY ENOTTY  "25">
TITY ETXTBSY  "26">
TITY EFBIG  "27">
TITY ENOSPC  "28">
TITY ESPIPE  "29">
TITY EROFS  "30">
TITY EMLINK  "31">
TITY EPIPE  "32">
TITY EDOM  "33">
TITY ERANGE  "34">

ardfs-config>
errors>
 <read>
   <error path="/testfile-retry">
     <n start-offset="10000" end-offset="10000" error-code="&EINTR;" times="10"/>
   </error>
   <error path="/testfile-fatal">
     <n start-offset="2" end-offset="2" error-code="&EIO;"/>
   </error>
 </read>
/errors>
tardfs-config>' > /tmp/petard-errors.xml
tardfs -e /tmp/petard-errors.xml -u /tmp/petard-data /tmp/petard-mnt
mp/petard-mnt
ff /tmp/petard-mnt/testfile-fatal /tmp/petard-data/testfile-fatal
: /tmp/petard-mnt/testfile-fatal: Input/output error
t /tmp/petard-mnt/testfile-fatal > /dev/null
 /tmp/petard-mnt/testfile-fatal: Input/output error
ff /tmp/petard-mnt/testfile-retry /tmp/petard-data/testfile-retry
: /tmp/petard-mnt/testfile-retry: Interrupted system call
t /tmp/petard-mnt/testfile-retry > /tmp/petard-testfile-retry
ff /tmp/petard-testfile-retry /tmp/petard-data/testfile-retry
sermount -u /tmp/petard-mnt

In the above example, we see that the diff program reports error conditions for both EIO and EINTR errors, while the cat program reports the EIO error but retries the read repeatedly when it gets the EINTR error until it succeeeds in successfully reading the data. We can use the strace command to verify that the error is, in fact, occurring:

tardfs -e /tmp/petard-errors.xml -u /tmp/petard-data /tmp/petard-mnt
mp/petard-mnt
trace cat /tmp/petard-mnt/testfile-retry > /dev/null) 2>&1 | grep read | head -n 12
(3, "\177ELF\2\1\1\0\0\0\0\0\0\0\0\0\3\0>\0\1\0\0\0\200\30\2\0\0\0\0\0"..., 832) = 832
(3, "1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14"..., 32768) = 8192
(3, 0x15a5000, 32768)               = -1 EINTR (Interrupted system call)
(3, 0x15a5000, 32768)               = -1 EINTR (Interrupted system call)
(3, 0x15a5000, 32768)               = -1 EINTR (Interrupted system call)
(3, 0x15a5000, 32768)               = -1 EINTR (Interrupted system call)
(3, 0x15a5000, 32768)               = -1 EINTR (Interrupted system call)
(3, 0x15a5000, 32768)               = -1 EINTR (Interrupted system call)
(3, 0x15a5000, 32768)               = -1 EINTR (Interrupted system call)
(3, 0x15a5000, 32768)               = -1 EINTR (Interrupted system call)
(3, "\n1861\n1862\n1863\n1864\n1865\n1866\n1"..., 32768) = 32768
(3, "14\n8415\n8416\n8417\n8418\n8419\n8420"..., 32768) = 32768
sermount -u /tmp/petard-mnt