Detailed SUBTERFUGUE Description


SUBTERFUGUE is a framework for observing and playing with the reality of Linux processes (i.e., what they see and do via their system call and signal interfaces.) This is done with tricks, which are components that watch and possibly modify a program's actions for a specific purpose.

SUBTERFUGUE comes with several tricks. One, called Trace, watches a program and produces output similar to strace(1). Another, ThrottleIO, restricts the total (average) I/O rate of a process. The most substantial trick, SimplePathSandbox, restricts the parts of the filesystem that a process (and its progeny) are allowed to read to and write from.

Tricks can generally be composed to produce a combined effect. So, for example, ThrottleIO could be combined with SimplePathSandbox to restrict I/O rate and path access, or a SimplePathSandbox could be sandwiched between two Trace tricks in order to observe the changes in the flow of system calls that SimplePathSandbox is making. Some trick combinations will not work, though, because they have contrary purposes or interfering implementations.

SUBTERFUGUE is meant to be extended with new tricks. A base class, Trick, provides the trick interface; new tricks can inherit directly from the base class or be derived from other existing tricks. Using the interface, a trick can modify the arguments of a system call (or even the call itself), change the result of the call, or skip the call entirely. Similarly, signals can be skipped or modified, and tricks are notified when processes terminate. Process memory can also be changed, permanently or just for the duration of a call.

In order to do its work, SUBTERFUGUE must carefully monitor process creation and termination. The wait system call must also be carefully emulated, since ptrace disrupts the normal wait reporting mechanism. SUBTERFUGUE tries hard to get the details right, but problems remain.


SUBTERFUGUE has a number of known limitations and caveats (not to mention bugs). Some problems are due to the current implementation or the limitations of the ptrace interface. Other more general problems arise from the way that the Linux kernel works or because of the general difficulty of controlling program behavior.

Implementation Problems

General Problems

Similar Tools

When I first started thinking about SUBTERFUGUE, I looked around at what had been done before; I was hoping that someone had already done it so that I wouldn't have to. :-) None of what I found seemed to be exactly what I was looking for, though; each had different features or goals or lacked an acceptable license. (I did get a lot of ideas, though, from reading strace's source code.)

Here are some related tools I've run across, in no particular order:

Future Directions

(to be written)

Appendix: The Five Degrees of Process Nescience and Impuissance

I find it useful to think about a continuum of process nescience (ignorance) and impuissance* (powerlessness) with regard to observation by a tracing process and a second related continuum for control. Each continuum has two dimensions: the degree to which it is affected, and the degree to which it may evade.

Observation Continuum
1The process is not observed.The process is not monitored.
2Observation is done in a manner that causes serious disruption, which the process is able to notice.The process can easily evade monitoring without intending to do so.
3Observation is done without serious disruption, but the process is still easily aware of the observation.The process can only evade monitoring by intentional action.
4Observation is not noticeable unless the process takes unusual steps.The process can only evade monitoring by taking steps that clearly demonstrate its intent to do so.
5The process is totally unaware of observation.The process cannot evade monitoring.

The control continuum is similar, except that the effect in question is the ability of the tracer to control the process' behavior, rather than to merely observe it.

* Yes, my thesaurus and I are good friends. :-)