LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

new entry converted to docbook from html by yours truly

This commit is contained in:
gferg 2002-01-30 17:08:49 +00:00
parent db1db17830
commit 17c2755049
1 changed files with 242 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

242
LDP/howto/docbook/Linux-Crash-HOWTO.sgml Normal file
View File

@ -0,0 +1,242 @@
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
<articleinfo>
<title>Linux Crash HOWTO</title>
<author>
<firstname>Norman</firstname>
<surname>Patten</surname>
<affiliation>
<address><email>nepatten@us.ibm.com</email></address>
</affiliation>
</author>
<pubdate>2002-01-30</pubdate>
<abstract><para>This document describes the installation and usage of the
LKCD (Linux Kernel Crash Dump) package. </para>
</abstract>
<revhistory>
<!-- Most recent revision goes at the top -->
<revision>
<revnumber>1.0</revnumber>
<date>2002-01-30</date>
<authorinitials>NM</authorinitials>
<revremark>Initial release.</revremark>
</revision>
</revhistory>
</articleinfo>
<sect1 id="intro"><title>Introduction</title>
<para>
The <emphasis role="strong">LKCD (Linux Kernel Crash Dump)</emphasis>
project is a set of kernel patches and utilities to allow a copy
of the kernel memory to be saved in the event of a kernel panic.
The saved kernel image makes forensics on the kernel panic
possible with utilities included in the package. Most commercial
Unix operating systems come with similar crash utilities, but
this package is fairly new to Linux and has to be added on
manually. The LKCD utility is not designed to gather helpful
information in the case of a hardware caused panic or a segment
violation. The complete LKCD package is available for download at
<ulink url="http://lkcd.sourceforge.net/">http://lkcd.sourceforge.net/</ulink>.
</para>
<sect2 id="copyright"><title>Copyright and License</title>
<para>This document is copyrighted (c) 2002 by Norman Patten.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover
Texts, and with no Back-Cover Texts. A copy of the license is
available at <ulink url="http://www.gnu.org/copyleft/fdl.html">
http://www.gnu.org/copyleft/fdl.html</ulink>. </para>
<para>Linux is a registered trademark of Linus Torvalds .
lkcd is distributed under the copyright of Silicon Graphics Inc. </para>
<para>Send feedback to
<ulink url="mailto:nepatten@us.ibm.com"><citetitle>nepatten@us.ibm.com</citetitle></ulink>.
</para>
</sect2>
</sect1>
<sect1 id="howitworks"><title>How LKCD Works</title>
<para>
When a kernel encounters certain errors it calls the
&quot;panic&quot; function which results from a unrecoverable
error. This panic results in LKCD initiating a kernel dump where
kernel memory is copied out to the pre-designated dump area. The
dump device is configured as primary swap by default. The kernel
is not completely functional at this point, but there is enough
functionality to copy memory to disk. After dump finishes
copying memory to disk, the system re-boots. When the system
boots back up, it checks for a new crash dump. If a new crash
dump is found it is copied from the dump location to the file
system, &quot;<filename>/var/log/dump</filename>&quot; directory
by default. After copying the image, the system continues to boot
normally and forensics can be performed at a later date. </para>
<sect2 id="whatyouneed"><title>What You Need</title>
<para>
<filename>lkcd-kernelxxx.diff</filename> file for patching the
kernel. The kernel version supported will change routinely.
<filename>lkcdutils-xx.src.rpm</filename> - this is the utilities
source and scripts you will need to setup and read a crash. At the
time of this writing there is a i386 binary rpm available from
<ulink url="http://lkcd.sourceforge.net/">lkcd.sourceforge.net</ulink>,
but you will still need the patches for the startup scripts from the
source rpm. </para>
</sect2>
</sect1>
<sect1 id="install"><title>Installation of lkcd</title>
<sect2><title>Installing From Source Code</title>
<para>
Get the <filename>lkcdutils-xxx.src.rpm</filename> and install it
using <command>rpm -i kcdutils-xxx.src.rpm</command> .
This will place a file called <filename>lkcdutils-xxx.tar.gz</filename>
in the <filename>/usr/src/redhat/SOURCES</filename> directory. This
file is a compressed tar image of the lkcd source tree.
Unwind the source in a directory of your choice like
&quot;<filename>/usr/src</filename>&quot; with
<command>tar -zxvf kcdutils-xxx.src.rpm</command> .
This will create a directory called
&quot;<filename>kcdutils-xxx</filename>&quot; which will contain
the LKCD utilities source.
</para>
</sect2>
<sect2><title>Building and Installing LKCD Utilities</title>
<para>
LKCD used the standard GCC compiler and make files. To build
the suite, cd to the LKCD src directory and
run <command>./configure</command> to build configuration files.
The next step is to run <command>make</command> to build
the utilities, and finally run <command>make install</command>
to install the utilities and man pages.
</para>
</sect2>
<sect2><title>What Gets Installed</title>
<screen>
/etc/sysconfig/dump # Configuration file for dump
/sbin/lcrash # The crash utility
/sbin/lkcd # Script to configure and save a crash
/sbin/lkcd_config # Configuration utility for dump
/sbin/lkcd_ksyms # Utility for reconstructing kernel symbols
/usr/include/sial_api.h # Header file for the SIAL API
/usr/lib/libsial.a # Simple Image Access Language library
/usr/man/man1/lcrash.1 # man page for lcrash
/usr/man/man1/lkcd_config.1 # man page for lkcd_config
/usr/man/man1/lkcd_ksyms.1 # man page for lkcd_ksyms
/usr/share/sial/lcrash/ps.sial # ps command implementation of SIAL
</screen>
</sect2>
<sect2><title>Installing LKCD Utilities From RPM</title>
<para>
You can install the pre-built utilities from rpm by running
<command>rpm -i kcdutils-xxx.rpm</command> . You will still need to
patch the kernel and install the startup script patches. However you
can bypass building the utilities step. </para>
</sect2>
<sect2><title>Patching the Kernel</title>
<para>
The next step is patching and rebuilding the kernel. You will
need to patch the kernel source with the
<filename>lkcd-xxx.diff</filename> file you downloaded from
<ulink url="http://lkcd.sourceforge.net/">http://lkcd.sourceforge.net/</ulink>.
Copy the patch into the same directory as your kernel and run
<command>patch -p0 &lt; lkcd-kernelxxx.diff</command> . Make sure
the patch you use is the same version as the kernel you
are patching. Next you will need to configure the kernel to enable
crash dump support. By default crash support is turned off after
applying the patch. If you use <command>make menuconfig</command>
or <command>make xconfig</command>, the &quot;LKCD support&quot;
option is under kernel hacking. You will also need
to enable other kernel features you might need. See the
<ulink url="http://linuxdoc.org/HOWTO/Kernel-HOWTO.html">The Linux
Kernel HOWTO</ulink> for further details. </para>
</sect2>
<sect2><title>Build and Install the Kernel</title>
<para>
The next is building and installing the crash enabled kernel. In the
kernel source directory run the following commands in order. </para>
<screen>
make depend
make install
make modules
make modules_install
</screen>
<para>
This will build and installing the new kernel, you will also need to
copy the <filename>Kerntypes</filename> file from the kernel source to
the <filename>/boot</filename> directory. You may also need to edit the
<filename>lilo.conf</filename> file to point to you new kernel. See
<ulink url="http://linuxdoc.org/HOWTO/Kernel-HOWTO.html">http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html</ulink>
for more information on building and installing a kernel. </para>
</sect2>
</sect1>
<sect1 id="setup"><title>Setup, Test, and Running crash</title>
<sect2><title>Setting up crash dump</title>
<para>
In order to save a core image that has been written into swap,
the image must be saved prior to swap being re-mounted during
boot. To accomplish this, the <filename>sysinit</filename>
startup file needs to be changed. The lkcd source includes a
<filename>scripts</filename> directory which contains patches
for various sysinit startup scripts. These patches add the
<command>lkcd config</command> and <command>lkcd save</command>
commands to enable crash dumps and to save any existing crash
dumps upon startup. </para>
</sect2>
<sect2><title>Testing crash</title>
<para>
To force a panic to test you new crash setup, compile the following
code with <command>cc -c -I/usr/src/linux/include panic.c</command> .
After building the <filename>panic.o</filename> module just
<command>insmod panic.o</command> to panic the kernel. </para>
<screen>
### panic.c ###########################
#define __KERNEL__
# MODULE
# include init_module(void)
int init_module (void)
{
panic(" panic has been called");
return 0;
}
</screen>
</sect2>
<sect2><title>Running crash</title>
<para>
To view your kernel core file <command>lcrash</command> needs
to be invoked with a couple of parameters: </para>
<screen>
<command>lcrash [ System.map file ] [ dump image ] [ Kerntypes ]</command>
Example:
<command>lcrash /boot/System.map ./dump.1 /boot/Kerntypes</command>
</screen>
<para>It will take a minute to load the kernel image into memory and drop
you into the crash shell. At the crash shell prompt you can type a
<userinput>?</userinput> to see the available commands. </para>
</sect2>
</sect1>
</article>