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

Running and configuring the syscall tracker
-------------------------------------------

Table Of Contents:

1. Automatic Loading of The Kernel Modules
2. Manual Loading of the Kernel Modules
3. Configuration using 'sct_config'
4. Tracing processes using 'sctrace'
5. Watching system call invocations. 
6. Automatic Unloading of The Kernel Modules
7. Manual Unloading of The Kernel Modules


1. Automatic Loading of The Kernel Modules
------------------------------------------

type (as root, since you're loading a module)

    ./sct_load

that's all. The script will load the modules for you and perform other
necessary initialization. If it fails, or you want to know more, read
the next section. 

2. Manual Loading of The Kernel Modules
-----------------------------
The kernel module is actually split into 2 modules. 'syscall_hijack.o'
responsiblity is to allow other modules to hijack system calls
(i.e. insert their own function in place of the original system call
function that the kernel provides). this module should be loaded
first, by typing: 

    insmod /path/to/syscalltrack/sct_rules_module/syscall_hijack.o

Note that the 'syscall_hijack.o' module cannot be unloaded, due to possible
race conditions when unloading it. However, if there are no hijacked system
calls (i.e. no rules configured for the syscall tracker), there is no
impact in system performance, other then the fact that the module occupies
some memory.

The second module, 'sct_rules.o', is responsible for system call tracking
operations and filter rules matching. load it next:

    insmod /path/to/syscalltrack/sct_rules_module/sct_rules.o

Once you have loaded the modules, you could check for their status using
the 'lsmod' command. Here is how they might look:

    # lsmod
    Module                  Size  Used by
    sct_rules              30684   0  (unused)
    syscall_hijack         12672   1  [sct_rules]


NOTE: if, while trying to load 'sct_rules.o', you get the following errors:

    # insmod ./sct_rules.o 
    ./sct_rules.o: unresolved symbol hijack_syscall_after
    ./sct_rules.o: unresolved symbol release_syscall_after
    ./sct_rules.o: unresolved symbol release_syscall_before
    ./sct_rules.o: unresolved symbol hijack_syscall_before

this means you haven't loaded the 'syscall_hijack.o' module first.


3. Configuration using 'sct_config'
----------------------------------
Once the kernel modules are loaded, its time to inject rules to them. This can
be done using the 'sct_config' utility. You would first need to write a
configuration file containing rule definitions. For convenience, we have
supplied an example rules file, 'sct_example.conf', in the 'sct_config'
directory. In order to load this file into the kernel module, run
sct_config as follows:

    sct_config upload sct_example.conf

After you do that, you may run 'lsmod' again, and see the use count for
the 'sct_rules.o' increasing. The use count shows how many different system
calls are hijacked by the module.

For more information about the configuration file format, as well
as other options of 'sct_config' (printing module's rules, deleting all
rules), please look in the 'doc' directory, at the file
'sct_config_manual.txt'.

4. Tracing processes using 'sctrace'.
-------------------------------------
Alternatively to using 'sct_config', you could use 'sctrace', which is
an strace(1) clone written using the syscalltrack infrastructure. Just
like strace, you can give it an executable to run 

   sctrace emacs

or a PID to attach to 

   sctrace -p `pidof emacs`

sctrace will then load rules logging every system call invocation by
that process. Every system call the process makes will be logged to
the logging device. 


5. Watching system call invocations.
------------------------------------
system call invocations are written to a logging device,
/dev/sct_log. syscalltrack supports several simultaneous readers of
the log device, each with its own parameters, such as the log format
or the maximum record length (more on these elsewhere). 

The simplest way to see the log output is to run 'sctlog' (as root)
after loading a few rules. You will see the log scrolling by. Since
the log device is a file (albeit a special one, a character device
file), you can redirect its output to another file, read from it in a
program and do other nifty things. 'sctlog' is a convenient wrapper
around 'sct_logctrl', which is a program used to control the log
device's behaviour, and accepts the same arguments that 'sct_logctrl'
does. You don't have to use it - 'cat /dev/sct_log' will work just
fine, but with the default log device options.


6. Automatic Unloading of the Kernel Modules
--------------------------------------------
As mentioned before, unloading is possible only for the 'sct_rules.o' module,
due to possible race conditions. However, before you unload this module,
you must first delete all module rules. You may do this with:

    sct_config delete

Note that the above might get stuck if the module is currently handling
any hijacked system invocation, so this operation might take a while.
After this operation succeeds, you can remove the module with:

    sct_unload

this script will unload the module and perform any cleanup necessary. 


7. Manual Unloading of The Kernel Modules
-----------------------------------------
As mentioned in the previous section, you must delete all of the rules
before attempting to remove the module. Once you've done that, you can
remove the module with

    rmmod sct_rules

Note: If you get an error message such as:

    sct_rules: Device or resource busy

this implies that the module still has some active rules, that cause it
to still hijack one (or more - depending on the use count) system
calls.
