/* 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: README,v 1.13 2002/09/30 07:04:05 mulix Exp $ */ 

syscalltracker - tracks system call invocation based on root-defined rules.
--------------------------------------------------------------------------

Table Of Contents:

1. What Is It?
2. When To Use It?
3. Current Status.
4. Compilation And Usage.
5. Near-Future Work.
6. Contact And Call For Participants.
7. License.


1. What Is It?
-------------
The syscall tracker allows you - the 'root' user - to track invocations of
system calls across your Linux system. You specify rules that specify which
system call invocations will be tracked, and what to do when a rule
matches a system call invocation. With the rule, you can also specify
an action that should be invoked when the rule is matched, such as
logging the math, or suspending or killing the process, or failing the
system call. 

2. When To Use It?
-----------------
Here are a few scenarios that will show what can be done with the system
call tracker. These scenarios actually happened to some of us on various
systems (not necessarily Linux) - and might have also happened to you.

-  you have an important file on the system mysteriously being deleted once
   in a while, and you wish to know which process is deleting the file.

   solution: add a rule to track any invocation of the 'unlink' system call,
   in which the 'pathname' parameter contains the name of the disappearing
   file.

-  you develop a multi-process system, and a process you're running
   suddenly receives a SIGTERM signal and dies. you want to know which
   process SENT this signal to your process.

   solution: add a rule to track any invocation of the 'kill' system
   call, in which the 'pid' parameter equals the pid of your precious
   process, and as an action for the rule - to log the activation, as
   well as suspend the process that invokes this system call. Then sit
   back and wait until the murderer makes its next move (i.e. kills your
   precious process) - then read the log, see which process killed your
   process (its still active, since it was suspended) and keep tracking
   from there.

-  you have a configuration file for a program which keeps being reset
   to a given state a while after you modify it. obviously, some program
   is updating this file's contents - but which program?

   solution: add a rule to track invocations of the 'open' system call,
   where the 'pathname' parameter contains the name of the config file,
   and the 'mode' flags contain any of 'O_CREAT', 'O_TRUNC', 'O_WRONLY'
   or 'O_RDWR'. Then modify your config file, wait until its contents
   is changed again, and look at the syscalls log for the culprit.

-  The permissions on some directory in your system keep changing to
   some value, despite you changing them to a different value, and you want
   to know who keeps changing them.

   solution: add a rule to track invocations of the 'chmod' system call,
   in which the 'path' parameter contains the name of the directory. You
   know the rest already...


3. Current Status:
-----------------

For the current status and supported features please see the 'NEWS' file.


4. Compilation And Usage:
------------------------
In order to compile the module, please look at the 'COMPILING' file.
In order to learn how to use the module, please read the 'RUNNING' file,
which will tell you how to load/unload the module, and how to use the 
'sct_config' utility to inject rule lists into the module.


5. Near-Future Work:
-----------------
Among the activities that are worked on now (and in the near future) are:
- Support for 'process tree' logging (i.e. parent process of the process that
  invoked the syscall, parent of that process, etc, up to the top-level
  process) - to allow answering questions such as 'ok, so the '/bin/kill'
  command killed my process, but who the heck invoked it?'.
- speed and locking optimizations (to reduce impact of rule matching on
  overall system performance).
- Support for a GUI application to configure tracking rules.

NOTE: The above is just what we plan to do real soon now. There are larger
plans for the long run, so keep tuned.

6. Contact And Call For Participants
------------------------------------
The project is being developed Using SourceForge's system. The project's home
page is http://syscalltrack.sourceforge.net (or http://syscalltrack.sf.net).

For general inquiries about the syscall tracker, bug reports and complaints,
please send email to syscalltrack-hackers@lists.sourceforge.net (this is the
developers mailing list, but for now it'll also be used for support purposes).

If you wish to participate in the project's development, please look
at our code-page, and register to the development mailing list - details
available at:
http://lists.sourceforge.net/lists/listinfo/syscalltrack-hackers
You may also wish to read the 'DEVELOPING' file for information for
developers.

The developers also hang out on the IRC channel #syscalltrack, on the
Efnet IRC network. Come by and say hi sometime...


7. License
----------
The syscall tracker is distributed under the GNU General Public License
(GPL) version 2, except for the 'sct_ctrl' library, which is
distributed under the GNU Library General Public License
(LGPL). Please look at the 'COPYING' file for a copy of the license.
