IMPORTANT: Due to handling semantics of user/kernel memory in concurrent environments, the sysjail tools, in inheriting from systrace(4), are vulnerable to exploitation. Details available here. Many thanks to Robert Watson for discovering these issues! Until these problems have been addressed, we do not recommend using sysjail (or any systrace(4) tools, including systrace(1)) for security purposes. sysjail is no longer maintained.

sysjail is a userland virtualisation system for OpenBSD and derivatives. It provides a similar function as FreeBSD's jail system while being significantly more flexible. The sysjail package provides jail(1), a drop-in replacement of FreeBSD's jail(8); sysjail(1), a more featureful version of jail(1); jls(1), a drop-in replacement of FreeBSD's jls(8); sjls(1), a more featureful version of jls(1); and sysjail(3), the function library backing these tools, designed to be droppable into any source tree. As with the original series, sysjail has a testing mechanism: sjtest(1).

The sysjail tools capture processes and their children under policies that govern the processes' interaction with resources. Policies define actions taken when certain system calls are intercepted by systrace(4); for example, a policy may categorically deny calls to reboot(2), or filter only a sub-set of processes to be manipulated with kill(2). In sysjail(3), policies define actions for all possible emulations for a system, allowing fine-grained control of system calls with differing semantics per emulation.

At this time, sysjail fully supports Linux and FreeBSD emulation, that is, Linux and FreeBSD binaries (with some exceptions) that run in sysjail(1) or jail(1) will receive the same protection as native binaries. Emulated binaries may either be started as shown below or executed from an existing jailed binary.

	Figure: jail environment as presented to host system. All non-jail processes may see and access those within the jail.
	Figure: jail environment as seen within the prison. Imprisoned processes may see one another, but may not see outside.

The sysjail tools sysjail(1) and jail(1) are implemented as user-space executables that control child processes via systrace(4) The device is primed by iterating over a set of tables defining intercepts for system calls, where tables are specific to the current operating system and emulation. Intercepted calls are subsequently mapped to function callbacks in these tables.

# echo $$ ; jail / ahost 127.0.0.1 /bin/sh
1975
# echo $$
2578
# kill 1975
/bin/sh: kill: 1975: No such process
# exit
exit

# echo $$ ; jail /emul/linux/ ahost 127.0.0.1 /bin/sh
1975
lappy:/# echo $$
28940
lappy:/# kill 1975
sh: kill: (1975) - No such process
lappy:/# exit
exit

The sysjail project is no longer maintained. If you'd like to do so, then please contact us.

The mldonkey system is known not to work properly when jailed, which seems to be an issue inherited from the systrace mechanism.

03-03-2009: sysjail is no longer being maintained. If you'd like to do so yourself, then please contact us.

18-07-2008: NetBSD support has been deprecated, as no up-coming NetBSD releases will support systrace(4). The mkjail(1) script now supports all, which builds all profiles. Tagged at version 1.2.34.

17-07-2008: bug-fixes for the hostname sysctl(3). sysjail.bsd.lv now has its own Xen image in the BSD.lv Project domain, allowing our own cvsweb system and listserv (see the documentation section). Tagged at version 1.2.33.

16-07-2008: bug-fixes for SPARC64 bus error crashes. This affected jls(1) and sjls(1), with possible effects also in sysjail(1) and jail(1), only for the SPARC64 architecture. Tagged at version 1.2.32.

26-05-2008: bug-fixes and re-run features in mkjail(1); bug-fixes in sysjail(1) and jail(1); Makefile cleaned up; and sources correctly linted. Caveats regarding OpenBSD device directories have been noted. OpenBSD port fixed. Web-site is now HTML, not XHTML. Tagged at version 1.2.31.

18-05-2008: bug-fixes in mkjail(1), sysjail(1), and jail(1); Makefile cleaned up; and sources correctly linted. Caveats regarding OpenBSD device directories have been noted. Tagged at version 1.2.29.

23-03-2008: added OpenBSD-4.3 support (as pulled from CVS). Tagged at version 1.2.28.

22-03-2008: added OpenBSD-4.2 support, fixed inclusion of OpenBSD-4.1 FreeBSD emulation, patched mkjail(1) to have site and sitelocal support. Tagged at version 1.2.27.

07-08-2007: fixed port template, Makefile, and stray strncat in sjtest.c.

02-08-2007: fixed a compile-time warning with 64-bit architectures (at kill.c:111). Please note that I don't have access to a 64-bit OpenBSD machine, but this should fix the issue. Tagged at version 1.2.25.

02-08-2007: sysjail(1) and jail(1) may be internally shut down by the standard reboot(8) (or halt(8), halt(8), ...) as it now appropriately handles calls to kill(2) and reboot(2). Note that a prison may not be rebooted, only shut down. See older news for caveats.

01-08-2007: added -b (background) and --allow-rlimit to sysjail(1). Added small tutorial in EXAMPLE section of manual page for both sysjail(1) and jail(1). Calls to setrlimit(2) that raise the maximum level are now by default denied (useful if one wants to fix resource limits before running a jail and be assured that the levels won't be changed). See older news for caveats.

30-07-2007: added mkjail(1) (merging of mksysjail-base and mksysjail-dev from old system). Otherwise, no code changes. See older news for caveats.

29-07-2007: added multiple address support to IPV4 and IPV6 by using the -4 and -6 flags in sysjail(1). jail(1) isn't effected. Same caveats continue with NetBSD. Support for NetBSD will be verified once I have access to a NetBSD machine.

28-07-2007: no code changes, but added a port-builder for OpenBSD. See download section.

24-07-2007: yet another pre-release (sysjail-1.2.19). Added --allow-ipc, --allow-all-domains, --allow-raw-sockets, and --allow-chflags to sysjail(1) for better compatibility with FreeBSD's jail(8). These are disabled by default in jail(1). Added FreeBSD emulation mode. Bugfixed calls to setdomainname(3) (now denied). Still doesn't support NetBSD. For testing purposes only.

22-07-2007: another pre-release (sysjail-1.2.18). Added ioctl(2) handling and began to differentiate in sjls(1). Still doesn't support NetBSD. Otherwise, feature-complete. For testing purposes only.

20-07-2007: initial pre-release of 1.0.x core re-write (sysjail-1.2.17). Note that this is not yet feature-complete: it lacks ioctl(2) handling. For testing purposes only.

28-10-2006: presentation at NYCBSDCon 2006. Slides [pdf.gz] and a short synopsis are available.

The more precise your bug reports, the faster the fix. Please carefully audit any reports you send. Bugs in documentation and related materials are just that: bugs.

Commercial enquiries: Maikls Deksters, dexter at ambidexter dot com.
System questions: Kristaps Džonsons, kristaps at kth dot se.

Sources

The cvsweb interface has been removed.

Mailing Lists

The mailing lists have been archived. If you'd like a copy of the archive, please contact us.

Manuals

The Unix manuals are, and will continue to be, the canonical sources for system documentation. Data in these manuals override anything you may read on this web page. Each of these manuals contains examples.

• sysjail(3): library function documentation.
• jail(1): drop-in replacement for FreeBSD's jail(8).
• sysjail(1): more featureful version of jail(1).
• jls(1): drop-in replacement for FreeBSD's jls(8).
• sjls(1): more featureful version of jls(1).
• sjtest(1): testing mechanism (do not run this on an un-jailed environment: you've been warned!)
• mkjail(1): simple tool to download and populate a prison

Supported Systems

The sysjail(1) and jail(1) utilities are designed for the following systems (the system will not compile for other versions!):

• OpenBSD: 3.9, 4.0, 4.1, 4.2, 4.3

In these systems, Linux and FreeBSD emulation modes are fully supported.

Extending

The sysjail(3) function library will work on any system supporting the systrace(4) device. Adding sysjail(1) and jail(1) to other systems with systrace(4) is largely a matter of porting ioctl(2) and sysctl(3) filters, and making sure that system call arguments are equivalent. Both sysjail(1) and jail(1) are internally very extensible and support, via sysjail(3), adding custom listeners, changing policies in run-time, re-assigning policy entities, etc. Please consult the documentation in the sysjail.h header file for a full list of available functions.

Related Materials

The following materials are related to sysjail:

• Džonsons, Kristaps. BSD Virtualisation with sysjail.
• Kamp, P-H., Watson, R., Confining the Omnipotent Root.
• Provos, N., systrace: Interactive Policy Generation for System Calls.
• Sarmentio, E., FreeBSD Architecture Handbook: The Jail Subsystem.
• Watson, R., Exploiting Concurrency Vulnerability in System Call Wrappers.

Installation

To install sysjail, download and unpack the source tree and execute make and make install. The system may be uninstalled by executing make uninstall. One may also build html manual pages with make www (requires rman), statically check sources with make lint, and build distribution archives (and source ports) with make dist.

The download section also contains OpenBSD ports. See the linked reference for installation instructions (we suggest using these rather than directly compiling the source). The ports packages do not install sysjail(3).

Thanks foremost to the OpenBSD, NetBSD and FreeBSD teams for providing free and secure operating systems. The sysjail system wouldn't exist without Niels Provos' systrace(4)device. The following is a list of contributors, and if we've not mentioned you, please let us know:

• Michael Lechtermann: bug-report (17 07 2008)
• Michael Lechtermann: bug-report and SPARC64 test system (15 07 2008)
• Jean-Gérard Pailloncy: bug-report (20 05 2008)
• Patrick Augé: bug-report and patch (18 05 2008, 20 05 2008)
• Michael: bug-report (14 05 2008)
• Felix Kronlage: mkjail patch (17 01 2008)
• Bernd Ahlers: port patch (03 08 2007)
• Charles Longeau: documentation patch (02 08 2007)
• Charles Longeau: bug-report (02 08 2007)
• Robert Watson: bug-report (29 11 2006)
• NYCBUG: sponsoring conference arrangements (26 10 2006)
• Julien Reveret: bug-report (08 09 2006)
• Gabriele Modena: bug-report (29 08 2006)
• Thorsten Glaser: documentation patches (27 08 2006)
• Sam Chill: bug-report (15 08 2006)
• Daniel de Kok: FreeBSD-compliance patches (06 08 2006)
• Joäo Pinheiro: feature patch (02 08 2006)
• Pēteris Duņaškins: mailing list (07 07 2006)
• Sigfred Håversen: initial port (24 05 2006)
• Pēteris Duņaškins: initial port (24 05 2006)

Special thanks to Maikls Deksters and the BSD.lv Project.