--- name: "sf" section: "1" platform: "linux" package: "subterfugue" version: "0.2.1a-9.5+b1" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/sf" --- # sf(1) utility to watch/alter a program's syscall/signal experience ## 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)](/ptrace/2.md) 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)](/strace/1.md), [**gdb**(1)](/gdb/1.md). - **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)](/python/1.md) modules, PYTHONPATH can be used to add new trick directories. ## SEE ALSO [**strace**(1)](/strace/1.md). 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 \. ## 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.