/* 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: COMPILING,v 1.15 2002/09/30 07:04:03 mulix Exp $ */

Compiling the system call tracker
---------------------------------

Table Of Contents:

1. Required Packages.
2. Compiling The Complete Tree.
3. Generated Binaries/Modules/Libraries.

Appendix A. Compiling Against a Distribution Kernel. 

1. Required Packages
--------------------
In order to compile syscall tracker, you will need:

- the source tree of your running kernel (or of a user-mode-linux kernel,
  if you want to test the module without endangering your Linux
  system). 
- the source code of the syscall tracker (containing sources for the kernel
  modules, as well as user-mode utilities/libraries used to configure the
  kernel module at runtime).
- the gcc and g++ compilers - compilation was tested with egcs 2.91.66,
  gcc 2.95.2, gcc 2.96-110 and gcc 3.0. Note that the 'sct_config'
  program (used to configure the kernel module at runtime) is written
  in C++, and thus requires g++.

Important: the kernel modules must be compiled with the same compiler that
was used to compile the kernel, or else binary compatibility is not ensured,
and the module might cause system crashes. In particular, the 2.X and 3.X
versions of the gnu compilers are not binary-compatible and shouldn't
be mixed.

2. Compiling The Complete Tree.
------------------------------
Run ./configure. If you wish to compile against a kernel which is not
the kernel you're currently running, provide the
--with-linux=/path/to/your/kernel. If you're using a default
installation kernel (the kernel that came with your distribution, not
one you compiled yourself), see appendix A. "Compiling Against a
Distribution Kernel". 

To compile syscalltrack, run 'make'. 

To install, run 'make install'. 'make install' by default needs to be
run as root, since it installs system wide applications and need write
permission to /usr and friends, but you can use the --prefix argument
to configure to compile and install syscalltrack as a user. To run
'make install' as root, try 'sudo make install', if you have sudo set
up, or 'su' and then 'make install'. 

3. Generated Binaries/Modules/Libraries.
---------------------------------------
The following binaries and kernel modules are generated by the compilation
process:

Directory module/*: 
   sct_rules.o - the main kernel module, used to perform syscall
	         tracking. 
   sct_hijack.o - a helper kernel module used for system call
		  hijacking. 
   Both of these are installed by default in
   /lib/modules/kernel_version/syscalltrack 

   syscalls.dat - A data file describing system calls. Installed by
		  default in /usr/local/etc/syscalltrack/syscalls.dat

   sct_load - A script to load the modules and perform the required
	      initialization (create the device filees, etc)
   sct_unload - A script to unload the module and perform the required
		cleanup. 

   Both of these are installed by default in /usr/local/bin

Directory sct_config:
   sct_config - a utility program, used for reading rules from a configuration
                file, and injecting them into the kernel
		module. Installed by default in /usr/local/bin/. 

Directory sctrace:
   sctrace - an experimental sctrace(1) clone, using the syscalltrack
	     infrastructure. Installed by default in /usr/local/bin/. 

Directory utils/sct_logctrl: 
   sct_logctrl - A log device control utility, to control various
	         parameters of the logging device. Installed by
		 default in /usr/local/bin/. 

Directory utils/sctdbg: 
   sctdbg - A debugging utility, used to inject debug values to the
	    kernel modules to tell them which areas to give debug
	    output for. Installed by default in /usr/local/bin/. 

Directory utils/sctlog: 
   sctlog - A utility to make using the log device comfortable with
	    various parameters comfortable. Installed by default in
	    /usr/local/bin/.

Directory sct_rules:
   libsct_rules.a = static library, provides an interface for user-mode
		    programs to create filter trees and test rules engines.

Directory sct_ctrl_lib:
   libsct_ctrl.a - static library, provides an interface for user-mode
                   programs to configure the kernel module at runtime.

Directory sct_parselib:
   libsct_parse.a - static C++ library, provides a (crude) interface for
                   parsing the syscalls.dat file and a syscalltrack config
                   file.
Directory tests:
   tester - a test program, used to perform stability test of the kernel
            module, by performing many rules addition and deletion, and then
            registering rules for most supported system calls, and invoking
            these system calls from many processes simultaneously.
   correctness_test.pl - a test script, used to perform correctness
		         tests. 
   release_tests.py - a script used to perform the previous two tests
		      in a loop, stopping if an error occured. 

Appendix A, Compiling Against a Distribution Kernel. 
---------------------------------------------------

These instructions describe how to compile syscalltrack against a
presupplied kernel, such as the kernels that Redhat ships with its
distributions. If you're compiling your own kernels, you can stop
reading now. Also, thes instructions are based on my experience with
Redhat 7.3 kernel 2.4.18-3. Experience with other distributions will
likely defer, but it is our hope that these instructions will be
sufficient to get you started. 

When compiling aginst a distribution kernel, you need two things. The
kernel's source tree, installed usually in /usr/src/linux-2.4.x, and
the .config file the kernel was compiled with. For Redaht, the kernel
sources are in the 'kernel-source' rpm and the kernel .config is in
the 'kernel' rpm. The .config, if installed, will be in
/boot/config-kernel-version. 

Once you have located your .config and the kernel sources, you need to
copy the .config to the kernel sources. This is because syscalltrack
uses the kernel's own build system, and the kernel's Makefile expects
to find the .config there. Also, since the kernel's compilation
process needs to write some temporary files into the kernel source
tree, you'll need to have sufficient permissions to do so - this
requires either making a copy of the kernel sources owned by your
user, or giving your user permissions to write into kernel source
tree, or compiling syscalltrack as root (not a good habit)... 

Once you've got your kernel tree set up, all you need is to compile
syscalltrack, as explained above. './configure && make && sudo make
install', and have fun!
