mirror of https://github.com/tLDP/LDP
243 lines
10 KiB
Plaintext
243 lines
10 KiB
Plaintext
<!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
|
|
"panic" 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, "<filename>/var/log/dump</filename>" 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
|
|
"<filename>/usr/src</filename>" with
|
|
<command>tar -zxvf kcdutils-xxx.src.rpm</command> .
|
|
This will create a directory called
|
|
"<filename>kcdutils-xxx</filename>" 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 < 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 "LKCD support"
|
|
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>
|
|
|