failgen README

failgen is a small tool used to geneated random failures in systrace(1) 
policies using a configurable number of failures. this is useful in fault 
injection tests where you want to observe the error handling of applications. 
uses a random array of error conditions from errno(2). failgen was inspired 
by dugsong.

failgen should work with any POSIX compliant AWK system.

USAGE:

failgen.awk <policy> <percent> [options]

the policy is a policy file for systrace. the percent is a decimal value
between 0 and 1 (ie 0.3) of the percent of "permit" rules you wish to
change to a "deny". 

options are
	-e   don't set "deny" for exit (causes core dumps)

EXAMPLE:

modify the policy to inject 10% failure cases, skipping native-exit denial:

$ failgen.awk /home/jose/.systrace/usr_sbin_host 0.1 -e  
Policy: /usr/sbin/host, Emulation: native
        native-fsread: filename eq "/usr/libexec/ld.so" then permit
        native-read: permit
        native-mmap: deny[edeadlk]
        native-issetugid: permit
	...

save this file in "/tmp/usr_bin_host" and use it now to test the policy:

$ systrace -a -f /tmp/usr_bin_host host www.monkey.org
/usr/libexec/ld.so: host: libc.so.28.5: No such file or directory

repeat the policy modification and application testing.

LIMITATIONS:

failgen has several major limitations:
	o it has a granularity at the syscall level. simply put this
	  means it can't allow you to allow a syscall to be permitted
	  several times and then fail randomly. any single syscall 
	  fails or passes in bulk.
	o it inserts random error codes which may or may not make sense.
	  you may wish to have an error code that does make sense for
	  any given operation, or just a blanket "deny".
	o it doesn't modify the arguments to syscalls. this would be
	  an interesting way to allow it to get more granularity, but
	  the logic there is very complicated and destined to fail
	  more often than work.

CHANGELOG:
	17 november 2002	released 0.1
	17 november 2002	released 0.2
		added support for "-e" to skip native-exit denial

AVAILABILITY:
	http://monkey.org/~jose/software/failgen/
	failgen is available under a BSD style license.
