/* This file is part of syscalltrack, a GNU/Linux kernel module and */
/* user space utilities for logging or modifying any system call    */
/* invocation.                                                      */
/*                                                                  */
/* Copyright (C) 2000-2002 guy keren, choo@actcom.co.il		    */
/* License: GNU General Public License                              */

/* $Id: DEVELOPING,v 1.13 2002/09/30 07:04:05 mulix Exp $ */ 

Information for developers and anyone interested in syscall tracker's internals
-------------------------------------------------------------------------------

Table Of Contents:

1. Source Tree Layout
2. Internal Design Documents
3. Running syscall tracker Under User-Mode Linux
4. Debugging syscall tracker Under User-Mode Linux
5. What Can You Do To Help Enhance syscall tracker?
6. CVS Repository Access Policy


1. Source Tree Layout
---------------------
The module's source tree contains the following directories:

doc - contains requirements and design  documents for syscall tracker and
      its various models. Look at 'index.html', as a starting point.
sct_rules - contains the source code of the rule-engine used by the
      kernel module. This includes code to handle a list of rules, code to
      handle generation of filter expression trees, code to encode rules and
      filter expressions into a string, and decode them from a string (used
      to pass filters from user-mode config programs to the kernel module),
      and code to evaluate filter expressions. This code is also used by
      user-mode programs to build rules that should be injected into the kernel
      module.
module - contains the main part of the 2 kernel modules - the
       sct_hijack module and the sct_rules module.
sct_ctrl_lib - contains code to build a library that wraps the
      interface for configuring the kernel module at runtime (adding rules,
      deleting rules...). used by user-mode programs that wish
      to configure the kernel module. 
sct_parselib - contains code (in C++) to build a library that provides a
      crude interface for parsing and validating the correctness of the
      syscalls.dat file, as well as sycalltrack rule config files, and
      allow accesisng this data in a structured manner.
sct_config - contains code (in C++) for a program that reads configuration
      files with rule definitions, and injects them into the kernel
      module, using the sct_ctrl_lib library. 
sctrace - contains the code for an strace(1) clone, using the
      syscalltrack infrastructure. 
utils/* - contains various small syscalltrack utilities. 

2. Internal Design Documents
----------------------------
All documentation, including internal design documents, is stored in the 'doc'
directory. Look in the 'index.html' file, at the 'Design Documents' section
for the relevant documentation.

Note: some of the documents are not completely up-to-date. Yet, they are a good
      place to start in order to understand the existing code-base.


3. Running syscall tracker Under User-Mode Linux
------------------------------------------------
When developing kernel code, any crash causes a system reboot, with possible
bad effects such as need to fsck all file-systems, and potentially file
system corruption. One method we use to void this problem, is doing the
development and debugging work under a user-mode Linux system.

User-mode Linux Is a port of the Linux kernel to the 'Linux' architecture.
This means, you run a Linux kernel (and a complete operating system on top
of it) on top of a running Linux system. Instead of dedicating a partition
for a file system for this virtual Linux system, a single file contains
a complete file system, so file system corruption in the virtual Linux won't
ruin your normal Linux installation. This approach also allows attaching
a debugger (such as gdb) to the virtual Linux kernel, and debugging it,
like you debug normal applications.

In order to install user-mode Linux ('uml'), please visit uml's home page,
at http://user-mode-linux.sourceforge.net/ . You will want to download their
kernel patch, as well as a file system image file. You might want to
download a file system image matching your favorite distribution, or
might want to experiment with a new distribution. In addition, you will
want to download the regular kernel's source for which the 'uml'
kernel patch is made. You need to compile your own kernel, and not use
the pre-compiled kernel images available on uml's site, so you will be
able to compile the module for the uml kernel, and so you'll be able
to debug the kernel and the module. 

NOTE: the file systems available on uml's site might be missing various
libraries required for the operation of the syscall tracker's user-mode
utilities. You could install them like you would on a "regular"
distribution, or if feeling brave, you could just copy those files
from your own system into uml's file system. Some file system images also
might be missing various utilities (such as your favorite editor) - so
you'll have to install or copy all their files (binary, shared
libraries they use, configuration files they rely on, etc) to uml's
file system. 

NOTE: As of 2002-06-13, if you want to use UML (user-mode-linux) with
syscalltrack you must have the latest UML patch (2.4.18-34), as the
syscalltrack test suite exposed a bug in UML which was fixed in
2.4.18-um32 and the syscalltrack modules require a patch which was
added to um-33. 

4. Debugging syscall tracker Under User-Mode Linux
--------------------------------------------------
In order to be able to debug the module, you should follow the instructions
on uml's web site for launching uml under 'gdb'. This will cause uml to
launch an extra xterm with 'gdb' running in it, when you boot uml. Type 'cont'
in the gdb command prompt to allow the boot process to continue. once
the system is up, load the syscall_hijack.o module and the sct_rules.o module,
as you do for normal usage. Then, follow the instructions on uml's site for
debugging modules, to be able to set breakpoints inside the module's code.
The method appears to have some quirks, so you'll have to play with it a bit
until you manage to get it working.

During a debug session, you might notice odd debugger behavior, such as
showing invalid contents for variables (even thought when the variable is
passed to a function, the value of the parameter suddenly changes into
a reasonable value), or errors such as "no variable 'i' defined in scope".
Either you have given a wrong address when telling gdb where the sct_rules.o
module is loaded in memory, or you landed on some uml quirk. In the later
case, just don't trust everything gdb tells you. You can still get useful
execution flow information from gdb, though.


5. What Can You Do To Help Enhance syscall tracker?
--------------------------------------------------
First of all, you could look at the 'tasks' page in the SourceForge project
web page (http://sourceforge.net/projects/syscalltrack/ -> Tasks), pick
an unassigned open task, announce on the syscalltrack-hackers mailing list
that you want to handle this task - and start coding.

Another option is to come up with your own ideas for enhancements, discuss
them on the mailing list, and then code them.

finally, and very important - look for bugs in the existing code, and fix
them. Look for code badly written - and suggest a rewrite (with a patch,
if you please).


6. CVS Repository Access Policy
-------------------------------
Read access to the CVS repository is granted to anyone. Write access is
limited, however.

Initially, to have your code changes/additions added to the CVS repository,
you'd have to go via the project admins - please send a unified diff
format patch of your changes, with an explanation of what they do, and
a suitable 'ChangeLog' entry, to the syscalltrack-hackers mailing list.
Your code will be reviewed, and if found appropriate (i.e. complete, with
no obvious extra bugs, and with a suitable programming style) - will be
committed into the CVS tree by one of the admins.

NOTE: before sending a patch, make sure that the modified code compiles
      cleanly (no warnings at all), test that it runs properly, 
      and does not break existing features. patches that don't comply won't
      be committed, and will earn you a 'careless hacker' badge of shame.
