sysjail — systrace process jailing library

sj_warn(const char *fmt, ...);

The sysjail functions control processes under systrace policies. Callers are responsible for managing actual system call interceptions; the functions handle processes, policies, emulations, and devices. The systrace.h and systrace.c files are designed to be drop-able into any source tree on a supporting system. This manual provides a high-level overview of the functions. For structure contents and detailed listenings, consult the header file documentation.

The sysjail function library may be used by dropping the sysjail.h and sysjail.c files into a source tree and interfacing with the functions. The source file does not require any specific compiler flags to run (assuming that sysjail.h is in the same directory): Before using the function library, it must be initialised with sj_init(). One or more (usually one) devices must then be initialised with sj_dev_new(), which registers physical devices with the system. A policy is the main concept in tracing processes. A policy, in the sense of sysjail, defines the set of intercepted system calls and their corresponding function callbacks. Policies are created by sj_pol_new() and filled in with sj_pol_set(). Policies may be changed at any time during system run-time with sj_pol_set(). This function dictates the routes taken by interceptions under given emulation modes. The general strategy for a policy is to register a system call for all potential emulations. For example, to intercept fcntl(2), one may set appropriate call-backs for 92 (native on OpenBSD) and 55 (Linux emulation). In many events, this call-back may be the same; however, some calls have different semantics between unices. Once one or more policies have been generated and (optionally) filled-in, they may be assigned to processes with sj_execv(). Policies are inherited by the children of the process executed by this function. Finally, one begins the event loop with sj_poll(). This function does not return until a SIGTERM is detected, all controlled processes exit, or a call-back function returns an exit request. Before exiting the process, sj_teardown() should be called to reclaim all resources properly.

During the sysjail library run-time, logging occurs in two ways. The first is using the standard err(3) and family. The second is using the internal methods as listed above. After forking a child, all logging uses the standard err(3) functions. Internally, sysjail only uses the provided log utilities. Developers are encouraged to use these log functions in writing intercept functions.

This is not intended to be a thorough examination of internals. Obviously, devices correspond to systrace(4) devices. It's unlikely that more than one device will be specified for a system. Policies are bound to devices. A policy is represented by a logical identifier, not to be confused with the policy number generated by systrace(4). Internally, sysjail manages multiple physical policies per logical policy in order to account for changing emulation, as systrace(4) dictates that only one emulation mode may exist per policy. Changing a policy with sj_pol_set() results in this change propogating to all current and future physical policies referenced by the logical identifier. In general, emulation is handled by registering all system call to a per-emulation policy. The system calls for execve(2) and execv(2) are then registered for a dummy callback (whether or not a callback has been specified), guaranteeing that we will see when emulation changes. Processes are started by sj_execv() with a policy and retain the policy during run-time (although the policy's "soft" values, those specified by sj_pol_set(), may be changed in run-time). The sj_poll() function loops over read events from systrace(4) (and auxiliary descriptors) until all processes are exhausted, a signal is received, an error occurs, or a call-back requests exit.

Between calls to sj_init() and sj_teardown(), the signals SIGTERM and SIGUSR1 have their handlers re-assigned and are masked. It's the caller's responsibility to re-assign these after sj_teardown(), if desired. Existing signal masks are not touched.

The following example has cb_native() and cb_linux() (not listed) handle call-backs for fcntl(2). The command-line arguments are used as file and parameters for execution. Note that error handling is omitted for brevity. This example must be executed as root.

systrace(4), chroot(2), execv(2), systrace(1), sysjail(1), jail(1), sjls(1), jls(1)

This is a complete re-write of the sysjail-1.0.4 core.

The sysjail function library was written by Kristaps Dzonsons for the bsd.lv project.