sf(1)
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@lists.sourceforge.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.