CHPOX - CHeckPOinter for linuX
==============================

Copyright (C) 2002, Olexander O. Sudakov <csaa@mail.univ.kiev.ua>
Copyright (C) 2002, Eugeniy S. Meshcheryakov <eugen@univ.kiev.ua>

This program licensed under the GNU General Public License. See COPYING for
more details.

-----------------------------

CHPOX is a set of the Linux kernel modules for transparent dumping of
specified processes into disk file and restarting ones.

FEATURES
========

  Dumping of one process or process with all it's children into disk file.
  Restarting of process or group of processes from file.
  Checkpoint file format is executable when CHPOX is loaded.
  CHPOX supports dumping of virtual memory, regular files, terminal state,
current working directory, multiple non-interacting processes.
  It does not crush on MOSIX [2] and openMosix [4], it is SMP safe.
  It works as a kernel module, so you does not need recompilation of the 
Linux kernel.

INSTALLATION
============

  Before installation you must have configured and compiled kernel sources.
  
  1. Unzip and untar archive with CHPOX sources:
  
         tar -xzf chpox-<version>.tar.gz
	 
  2. 'cd' to the directory containing the source codes and run './configure'
script:
  
         cd chpox-<version>
	 ./configure
	 
  you can pass path to Linux sources to 'configure' if it is not 
'/usr/src/linux':
  
         ./configure --with-linux=/path/to/kernel/sources
	 
  3. Run 'make', 'make install' and 'depmod -a':

         make
	 make install
	 depmod -a
	 
  !!!WARNING: Compile CHPOX with the same compiler the kernel was compile.
  !!!WARNING: Recompile CHPOX after recompiling kernel
  
USING
=====

  Before starting checkpointing and restoring processes you must load CHPOX
modules:
         
         modprobe chpox
  
  or

         insmod vmadump; insmod chpox

  Checkpointing of processes is controlled by proc interface. You can register
or unregister process(es) by writing string <pid>:<signal>:<arg> into file 
'/proc/chpox/register'. This will cause registration or unregistration of 
process (possibly with all it's child processes) with identifier <pid>.
Passing <arg> == 0 unregisters process with given <pid> (if <pid> is 0 it 
unregisters all registered processes). If <arg> isn't 0 it registers given
process (or group of processes). Dump file name is created as 
"/tmp/chpox-<command_name>-<pid>-<time>".

The meaning of <arg>:
  - if bit 2 is set then executable file is included into dump. It may be
  useful to transfer processes between different machines with the same
  shared libraries.
  - if bit 3 is set then shared libraries which registered with 'vmadlib' 
  will be included into dump file.
  - if bit 4 is set then CHPOX will checkpoint all child processes of given
  one.

Examples:

  Registration of process with PID 1234 for checkpointing with signal 31 
  (SIGSYS):
  
     echo "1234:31:1" > /proc/chpox/register

  Registration of process with all it's child processes:

     echo "1234:31:9" > /proc/chpox/register

  Unregistration of one process:

     echo "1234:0:0" > /proc/chpox/register

  Unregistration of all registered processes:

     echo "0:0:0" > /proc/chpox/register

     
  After registering of process you can checkpoint it as many times as 
  necessary by sending signal to it:
     
     kill -31 1234

     
  File "/proc/chpox/info" holds information about registered processes 
  in form:
  
<pid>:<signal>: [<flag>|<number of checkpoints>] -> <filename> [<last checkpoint time>]

  Flag is one of:
    C - new entry
    S - unused
    O - last request was processed correctly
    E - last request caused an error

Example:

2108:31:9 [O|1] -> /tmp/chpox-bash-02108.1040130754.383009 [1040130768.799984]

OPERATION DETAILS
=================

Registration of process for checkpoint will block the specified signal of 
specified process. Blocking of signal is doing by setting the notifier 
function that returns 0. When specified signal is sent to process notifier is 
executed in the context of process being checkpointed.  
During execution of notifier, vmadump and dump of files information are 
executed. If MOSIX is configured process returns home before dumping. 
This kind of operation is similar to EPCKPT [1]. EPCKPT is very powerful 
(supports almost all except sockets) but it needs patching of kernel and thus
does not work with MOSIX. CRAK tries to stop the process before checkpointing
and after that operates with its structures. CRAK does not designed for SMP 
(at least version for Linux-2.4.4) but it is declared that it supports 
sockets (not in version for Linux-2.4.4). 
All features from vmadump [3] may be used as without chpox 
(see vmadump documentation).

AUTHORS
=======

   Olexander O. Sudakov <csaa@univ.kiev.ua>
   Eugeniy S. Meshcheryakov <eugen@univ.kiev.ua>

CHPOX based on

   VMADUMP           by Erik Hendriks <erik@hendriks.cx>
   EPCKPT            by Eduardo Pinheiro
   CRAK              by Hua Zhong <huaz@cs.columbia.edu>

VERSION
=======

  This is version 0.3 alpha. It tested with Linux kernel version 2.4.18 
  and 2.4.19.

BUGS
====
  
  Probably many?..

TODO
====

  Support for pipes, sockets, shared memory, System V IPC.
  Better integration with MOSIX and openMosix.

LINKS
=====

  1. http://www.chechpointing.org/ Checkpointing.org: The home to checkpointing packages
  2. http://www.mosix.org/         MOSIX
  3. http://www.beowulf.org/software/bproc.html BPROC: Beowulf Distributed Process Space
  4. http://www.openmosix.org/     The openMosix Project
