mkexec/3.0/2.6 README-v3,NONE,1.1 README,1.2,1.3

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/mkdump/mkexec/3.0/2.6
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv7814

Modified Files:
	README 
Added Files:
	README-v3 
Log Message:
for v3

Index: README
===================================================================
RCS file: /cvsroot/mkdump/mkexec/3.0/2.6/README,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** README	24 Mar 2006 01:36:56 -0000	1.2
--- README	28 Mar 2006 00:43:43 -0000	1.3
***************
*** 5,10 ****
     http://mkdump.sourceforge.net

! *** This document describes the part of the backword compatibility of 
! 	version 2 update 1. ***

  Contents of this package
--- 5,15 ----
     http://mkdump.sourceforge.net

! Note
! ----
! 
! This document describes the part of the backword compatibility of version 2 update 1. 
! See README-v3 for version 3.
! If you have not used the mkdump yet, use version 3.
! 

  Contents of this package
***************
*** 58,62 ****
    +-----------+---------------+--------+ +--------+-------+ +---------+

!   for vanilla 2.4.27, use the version 1.0 of mkdump at this moment.

--- 63,67 ----
    +-----------+---------------+--------+ +--------+-------+ +---------+

!   for vanilla 2.4.27, use the version 1.0 of mkdump.

***************
*** 160,164 ****
     # mkdir /usr/src/modules
     # cd /usr/src/modules
!    # tar -xf mkexec-module-2.1.tar

  2) Edit the Makefile
--- 165,169 ----
     # mkdir /usr/src/modules
     # cd /usr/src/modules
!    # tar -xf mkexec-module-3.0.tar

  2) Edit the Makefile
***************
*** 291,295 ****
    ex.
    # cd /usr/local/src/
!   # tar xf mkdutils-2.1.tar

  2) Make
--- 296,300 ----
    ex.
    # cd /usr/local/src/
!   # tar xf mkdutils-3.0.tar

  2) Make
***************
*** 311,338 ****
    the /etc/mkdump/mkdump environment file.

! 3) mkd_chk
! 
!   check the dump device whether the dump was captured or not.
!   this command is used in mkd_save internaly.
! 
! 4) /etc/mkdump/mkdump

    see mkdump-config-sample.

! 5) mkd_conv

!   There are dump format conversion tools.
!   "mini kernel dump" only offers the dump capturing function.
!   You can use any analisys tool by converting the dump format.
!   This directory includes three tools.
!    - mkd2lkcd_i386
!      mkdump format to lkcd format (for i386)
!    - mkd2lkcd_x86_64
!      mkdump format to lkcd format (for x86_64)
!    - elf2lkcd_i386
!      vmcore format to lkcd format (for i386)

!   These codes also intend to explain the mkdump format and to
!   show the format conversion is easy task.

    Note: we use "crash" command rather than "lcrash" command.
--- 316,331 ----
    the /etc/mkdump/mkdump environment file.

! 3) /etc/mkdump/mkdump

    see mkdump-config-sample.

! 4) mkd_conv

!   This is a dump format conversion and save tool. It converts to the LKCD format.

!   mkd_conv file1 file2
!     file1: the dump partition (ex. /dev/hda7)
!     file2: the output file
!   for other functions see the souorce code.

    Note: we use "crash" command rather than "lcrash" command.

--- NEW FILE: README-v3 ---
README for Mini Kernel Dump (version 3)
------------------------------------------------

See the following URL for more information about MKDUMP.
   http://mkdump.sourceforge.net

Note
----

  The followings are main changes from version 2 update 1.

  * now a mini kernel is loaded to the standard address.
  * the dump output part of a mini kernel can be a kernel module.
  * initrd is supported.

Contents of this package
------------------------

  x. README-v3 (this file)
  a. mkexec kernel module
     mkexec-module-3.0.tar
  b. mkexec kernel patch
     b-1) mkexec-patch-2.6.12-2.1
     b-2) mkexec-patch-deb-2.6.8-2.1
  c. mini kernel module
     minik-module-3.0.tar
  d. mkdump utilities
     mkdutils-3.0.tar

  * support architecture: i386, x86_64

  * the following combinations are available

  = for vanilla kernel
  +-----------+---------------+--------+ +--------+-------+ +---------+
  | mkexec    | mkexec        | mkexec | | mini   | minik | | utility |
  | kernel    | patch         | module | | kernel | module| |         |
  +-----------+---------------+--------+ +--------+-------+ +---------+
  | 2.6.12    |  b-1          |   a    | | 2.6.x  |   c   | |    d    |
  +-----------+---------------+--------+ +--------+-------+ +---------+
  = for Red Hat
  +-----------+---------------+--------+ +--------+-------+ +---------+
  | 2.4.21-20 | no need       |        | |        |       | |         |
  |  or later |               |   a    | | 2.6.x  |   c   | |    d    |  
  +-----------+---------------+        | |        |       | |         |
  | 2.6.9-x   | no need       |        | |        |       | |         |
  +-----------+---------------+--------+ +--------+-------+ +---------+
  = for debian
  +-----------+---------------+--------+ +--------+-------+ +---------+
  | 2.6.8-16  |  b-2          |   a    | | 2.6.x  |   c   | |    d    |
  +-----------+---------------+--------+ +--------+-------+ +---------+

  note: we use 2.6.9 or later for a mini kernel.

Installation
------------

Mini Kernel Dump consists of three parts:

 * minik - Mini Kernel
   Patch to build a special Linux kernel version to dump all the memory to
   a device.

 * mkexecpatch - MKEXEC kernel
   Hook and support functions to be able to load "mkexec-module".
   This patch must be applied to your standard running Linux kernel to be able
   to dump its faults.

 * mkexec-module - MKEXEC kernel module to load Mini Kernel
   Load this Linux kernel module to "mkexecpatch"-ed Linux kernel to be able to
   use the dumping functionality. This module will enable you to load
   'minik - Mini Kernel' into memory and automatically launch it when needed.

Build Mini Kernel
-----------------

1) Extract the source
   ex.
   # mkdir /usr/src/modules
   # cd /usr/src/modules
   # tar -xf minik-module-3.0.tar

A: build as a kernel module
  2) Edit the Makefile.base

   # cd /usr/src/modules/minik
   # vi kernel/Makefile.base

   Change "KDIR", "KVER" for your environment.

  3) make
   # make; make install

B: static link
  2) copy minik_dump.c to the target source tree

   # cp kernel/minik_dump.c <kernel-src>/init

  3) chage <kernel-src>/init/Makefile

   add "minik_dump.o" the following line.
   --------------------------------------------------------------------------
     obj-y := main.o version.o mounts.o initramfs.o minik_dump.o
                                                    ^^^^^^^^^^^^
   -------------------------------------------------------------------------

  4) make

   # cd <kernel-src>
   # make

Note:

  * The mini kernel should be as small as possible.
    ex. the network should not be configured.
  * Do not use "bzImage" for mkexec, 
     use: arch/[i386|x86_64]/boot/compressed/vmlinux.bin

Build MKEXEC kernel
-------------------

  Note: for RHEL3/4 this is not necessary.

1) Prepare the target kernel
   ex.
   # cd /usr/src
   # tar -xjf linux-2.6.12.tar.bz2
   # mv linux-2.6.12 linux-mkexec

2) Apply the patch
   ex.
   # cd /usr/src/linux-mkexec
   # patch -p4 < mkexec-patch-2.6.12-2.1

3) Configuration

   # make menuconfig

   Turn on CONFIG_DUMP_MKEXEC:
   * 2.6.12 + mkexec-patch-2.6.12-2.1
     Select "Mini Kernel - mkexec" in the "Processor type and features"
   * other
     no need

4) Build
   ex.
   # make bzImage; make modules; make modules_install; make install

Build MKEXEC Kernel Module
--------------------------

1) Extract the source
   ex.
   # mkdir /usr/src/modules
   # cd /usr/src/modules
   # tar -xf mkexec-module-3.0.tar

2) Edit the Makefile

   # cd /usr/src/modules/mkexec
   # vi kernel/Makefile

   Change "ARCH", "KTYPE", "KVER", "TOPDIR" and "THISDIR" for your environment.

   ex.
   ARCH = x86_64     # specify "i386" or "x86_64"
   KTYPE = 24         # specify "24" for kernel 2.4 or "26" for kernel 2.6
   TOPDIR = /usr/src/linux-mkexec  # specify the top directory of mkexec kernel
   THISDIR = /usr/src/modules/mkexec/kernel  # specify the directory this Makefile exists
   KVER = 2.6.12-mkexec      # specify the kernel suffix (=> /lib/modules/$(KVER))

3) Make symbolic link

   # ln -s asm-i386 include/asm     # for i386
   or
   # ln -s asm-x86_64 include/asm   # for x86_64

4) Make

   # make

Make initrd image
----------------

  For example, on RHEL4: simply execute the following command
    # mkinitrd mkinitrd --with=mkdump initrd.img 2.6.12

  For other distribution see the document for that system.

Run Mini Kernel Dump
--------------------

1) Load the MKEXEC module

   # insmod /usr/src/modules/mkexec/kernel/mkexec.o    # for kernel 2.4
   or
   # insmod /usr/src/modules/mkexec/kernel/mkexec.ko   # for kernel 2.6

2) Load the Mini kernel

  Set the dump device:
  ex.
  # echo "0x800012" > /proc/mkexec/dumpdev

      Specify the device number of the dump device. Bits 20..31 are block device
      major number, bits 0..19 are block device minor.
      Check the device number of your device by command like: ls -l /dev/sda4

  Set the boot parameters of the mini kernel:
  ex.
  # echo "console=tty0 console=ttyS0,115200n8r" > /proc/mkexec/parameter

      * for RHEL3/4, the following parameters must be specified
        "lpj=" and "no-hlt"
        ex.
        # echo "lpj=2367488 no-hlt" > /proc/mkexec/parameter

      * the following parameters are available for the mini kernel
        mkdump_reboot: specifies action after dump done
                       mkdump_reboot=reboot  (default)
                                    =halt    
                                    =poweroff  
                                    =off
                       note: working poweroff is hardware dependent

        dump_delay: specifies wait time before dump start (for waiting completion of 
                    device driver initialization)
                    dump_delay=second  (default == 0)

        ex.
        # echo "mkdump_reboot=halt dump_delay=5" > /proc/mkexec/parameter

  Set the path name of the mini kernel:
  ex.
  # echo "/usr/src/linux-minik/arch/i386/boot/compress/vmlinux.bin" > /proc/mkexec/path

  Set the amount of memory the mini kernel uses:
  ex.
  # echo 16 > /proc/mkexec/mem          # reserve 16MB of memory

      This is necessary only for RHEL3 i386. This must be multiple of 4. 

  Set the path name of initrd image:
  ex.
  # echo "/boot/initrd-minik.img" > /proc/mkexec/initrd

  Load the mini kernel image:

  # echo 9 > /proc/mkexec/stats

  Note: the "mkd_load" utility make above tasks easy. 

Start the Mini Kernel
---------------------

  If BUG(), panic() or nmi_watchdog occurs the Mini Dump kernel will be launched.

  Manual capturing dump: echo 2 >/proc/mkexec/stats

  Note: for x86_64, /proc/sys/kernel/panic_on_oops should turn on.
        # echo 1 > /proc/sys/kernel/panic_on_oops

*** utilities for the mkdump ***

Installation
------------

1) Extract the source

  ex.
  # cd /usr/local/src/
  # tar xf mkdutils-3.0.tar

2) Make

  # cd /usr/local/src/mkdutils
  # make

Contents of this package
------------------------

1) mkd_load

  load and setup the mkdump according to the /etc/mkdump/mkdump environment file.

2) mkd_save

  save the dump from the dump device to a permanent directory according to
  the /etc/mkdump/mkdump environment file.

3) /etc/mkdump/mkdump

  see mkdump-config-sample.

4) mkd_conv

  This is a dump format conversion and save tool. It converts to the LKCD format.

  mkd_conv file1 file2
    file1: the dump partition (ex. /dev/hda7)
    file2: the output file
  for other functions see the souorce code.

  Note: we use "crash" command rather than "lcrash" command.

Remark
------

  these programs are offered as sample programs. there is nowarranty for 
  these programs.

--
Portions Copyright (C) 2004-2005 NTT DATA CORPORATION.
Portions Copyright (C) 2004-2005 VA Linux Systems Japan K.K.