home

systrace port for FreeBSD

Here you can find information about systrace port for FreeBSD. Systrace was written by Niels Provos and is part of OpenBSD and NetBSD. Robert Watson made some comments on systrace long time ago (2002) and proposed that someone should "port it over" and report problems in which they run into. Following informations are meant to fullfil just that.

In october 2003, I've got patches from Dr. Rich Murphey (WhiteOakLabs.com), who was working on port to FreeBSD 5.1. My work is based on these patches - I basically made some changes to make it work on RELENG-4 i386 systems, debugged a few kernel bugs, added debug messages, tweaked systrace userland. This patch is kind of dirty and not (yet) working on 5.x systems, but mostly works. Kernel panic may be still possible.

Current status: preparing to start working on the port again. I have to get some hardware first.

Download section

• kernel patch (20040309 snapshot) (applies cleanly to FreeBSD 4.9-RELEASE and 4_9_RELENG (patch branch) with src-sys and src-sys-crypto cvsup collections)
  
• systrace userland (20031208 snapshot)
  
• xsystrace port (20040202 snapshot)
  note: xsystrace doesn't yet work as expected
  
• src-4.9-RELENG-systrace.patch (20040202 snapshot) patch against src/sys/ directory. (for release building)
• FreeBSD systrace-enabled release based on 4.9-RELEASE released (20040602 snapshot)

Changelog

• 2004/03/09 kernel patch applies cleanly to 4_9_RELENG; two production FreeBSD systems running with this patch have more than 14 days uptime now. However, daemons running under systrace occasionaly stop working.
• 2004/02/02 panic when rebooting with systraced processes seems to be solved.
• 2004/02/06 systrace FreeBSD distribution based on 4.9-RELEASE released

Installation process (for RELENG-4)

1. compile kernel with systrace patch:
    cvsup supfile-4.9-R
    cd /usr/src/sys && patch -p0 < systrace-4.9-kernel.patch
    now go compile kernel /sys/i386/conf/HACK-systrace
2. install systrace device via
    cd /dev/ && mknod systrace c 251 0 && chmod 644 /dev/systrace
    create dir for global policies:
    mkdir /etc/systrace; chmod 755 /etc/systrace
3. install userland (unpack the tgz file into /usr/src and do make && make install)
4. rebuild libkvm and libkvm-dependent binaries (ps, top, w, ...) with new proc.h header file
5. if you are going to use xsystrace port, untar it into /usr/ports and run make install in it.
    (make sure you have XFree86 port/pkg installed)

Release build (for 4.9-RELEASE)

If you want to build whole release with systrace, use following steps:

1. get 4.9-RELEASE sources (e.g. via cvsup as above)
   do not forget to fetch /usr/src/release directory containing scripts for release building. (via src-release collection)
   
2. get patch against /usr/src/sys , systrace userland archive (from download section) and create build-script.sh. script:

      cat << EOF >> build-script.sh
      #!/bin/sh
      cd usr/src; 
      tar xvfz /PATH/TO/SYSTRACEUSERLAND-ARCHIVE/systrace-4.9-userland.tgz
      EOF
      

   
   Do not forget to modify the right location of systrace userland tgz file.
   
3. build release via
   

      cd /usr/src/release;
      make release BUILDNAME=4.9-RELEASE-systrace \
         RELEASETAG=RELENG_4_9_0_RELEASE \
         CHROOTDIR=/tmp/Freebsd-build CVSROOT=anoncvs.server:/dir \
         NODOC=YES NOPORTS=YES \
         LOCAL_PATCHES=src-4.9-RELENG-systrace.patch \
         LOCAL_SCRIPT=build-script.sh
      

   Change BUILDNAME, CHROOTDIR and CVSROOT according your needs.
   

TODO (aka what doesn't work)

There is lot of things to do:

- fix local root hole (fixed in NetBSD cvs)
- find more bugs causing panics (if any)
- race conditions (found by David Malone, who did the initial FreeBSD port) solution (if any)
- clean up the code
- xsystrace debug
- port to archs other than i386
- 5.x port (in progress)
- syscall emulation
- invalid syntax in systrace policy can cause panic (?)
- make some massive testing
- test it thoroughly (create set of regress tests)
- sync with current code from NetBSD (now it's somewhere before cradle mode implementation)
- add code to export systrace statistics via sysctl
- ...

Systrace (programmers') documentation

Here will be light introduction to systrace internals. (in progress)

- systrace overall design
- kernel/userspace communication
- porting issues