sf - utility to watch/alter a program's syscall/signal experience

sf [options] command command-arg...

The sf utility runs command under the control of one or more SUBTERFUGUE tricks. These tricks can observe and alter the behavior of command, (and all of the subprocesses and threads it starts) using the ptrace(2) system call. For example, the NetFail trick will cause network connection attempts to fail with "host unreachable" errors.

-t, --trick=TRICK[:OPTIONS]

use trick with given options, multiple tricks may be given and apply successively, left-to-right

-o, --output=FILE

direct sf output to a file, or a file descriptor (if FILE is a number)

-n, --failnice

allow the command to continue if sf should abort (otherwise sf will try to SIGKILL all of the command's processes as it dies)

--waitchannelhack

use wait channel hack (slower, but required for unpatched kernels 2.3.99-2.4.0test9)

-d, --debug

show debug output

--slowmainloop

disable the optimized main loop, for debugging purposes

-h, --help

display help (including help for specified tricks) and exit

-V, --version

output version information and exit

A trick is a small python module that is interposed between command's processes and the kernel. It can catch system calls invoked by these processes and signals sent to them, and observe, cancel, or rewrite them. In this way, tricks can exert quite a bit of control over the "reality" these processes experience.

The set of tricks that come with SUBTERFUGUE is growing rapidly. (You can easily add more yourself; see the web site for more details.)

The OPTIONS part of a trick argument, if given, is a tiny chunk of python code which assigns values to the specified options. So, for example, "--trick=Spam:n=1;foo='bar'" would assign option n the numeric value 1 and option foo the string value 'bar'.

Here are descriptions of a few of the more stable and interesting tricks currently available:

Trace

traces system calls, signals, and process exits, like strace(1), gdb(1).

SimplePathSandbox

controls which files a command can read from and write to.

NetFail

causes network connection attempts to fail with a "host unreachable" error (and listen attempts to fail with "operation not supported").

NetThrottle

limits the amount of network bandwidth an application uses; it has a Gtk interface so that the limit can be adjusted interactively.

Use the --help flag or check the web site to get more information about the usage and limitations of each trick.

Since tricks are python(1) modules, PYTHONPATH can be used to add new trick directories.

strace(1).

More complete documentation is available at 'http://subterfugue.org'.

Written by Mike Coleman, with contributions by Pavel Machek.

Yes, there are bugs. SUBTERFUGUE is still fairly experimental. See the web site and the TODO file.

The biggest known bug is that each process run under sf will not have its zombie reaped until sf itself exits, which can lead to a lot of zombies, filling your process table, etc. Solving this problem will require a kernel patch or a rewrite of sf, unfortunately.

Don't run sf as root, or with programs where a loss of state would be disastrous (e.g., fetchmail), unless you really know what you're doing.

Report bugs to <subterfugue-dev@lists.sourceforge.net>.

SUBTERFUGUE, including the sf program, is free software, distributed under the terms of the GNU GPL; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.