NAME
sf − utility to watch/alter a program’s syscall/signal experience
SYNOPSIS
sf [options] command command-arg...
DESCRIPTION
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.
OPTIONS
−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
TRICKS
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.
ENVIRONMENT
Since tricks are python(1) modules, PYTHONPATH can be used to add new trick directories.
SEE ALSO
More complete documentation is available at ’http://subterfugue.org’.
AUTHORS
Written by Mike Coleman, with contributions by Pavel Machek.
BUGS
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 [AT] lists.net>.
UNRESTRICTIONS
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.