<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>

  <articleinfo>
    <title>Linux Crash HOWTO</title>

    <authorgroup>
    <author>
      <firstname>Norman</firstname>
      <surname>Patten</surname>
      <affiliation>
	<address><email>nepatten@us.ibm.com</email></address>
      </affiliation>
    </author>
<author>
<firstname>Vertaald door: Ellen Bokhorst</firstname>
<surname>Bokhorst</surname>
<affiliation>
<address><email>bokkie@nl.linux.org</email></address>
</affiliation>
</author>
</authorgroup>
    <pubdate>30-01-2002</pubdate>
    <abstract><para>In dit document wordt de installatie en het gebruik
    van het LKCD (Linux Kernel Crash Dump) package beschreven. </para>
    </abstract>

    <revhistory>
       <!-- Most recent revision goes at the top -->
       <revision>
         <revnumber>1.0</revnumber>
         <date>30-01-2002</date>
         <authorinitials>NM</authorinitials>
         <revremark>Initi&euml;le release.</revremark>
       </revision>
    </revhistory>

  </articleinfo>

  <sect1 id="intro"><title>Introductie</title>
    <para>
    Het <emphasis role="strong">LKCD (Linux Kernel Crash Dump)</emphasis>
    project bestaat uit een set kernelpatches en utility's om kernelgeheugen
    te kunnen kopi&euml;ren om het op te slaan in geval van een kernel panic.
    Het opgeslagen kernelimage maakt onderzoek op de kernelpanic mogelijk
    met utility's die in het package zijn opgenomen. De meeste commerci&euml;le
    Unix besturingssystemen worden met vergelijkbare crash utility's
    geleverd, maar dit package is tamelijk nieuw voor Linux en het moet
    handmatig worden toegevoegd. Het LKCD utility is niet ontworpen
    voor het verzamelen van behulpzame informatie in geval van een
    door de hardware veroorzaakte panic of een segment violation.
    Het volledige LKCD package is beschikbaar voor download vanaf
    <ulink url="http://lkcd.sourceforge.net/">http://lkcd.sourceforge.net/</ulink>.
    </para>

    <sect2 id="copyright"><title>Copyright en licentie</title>

      <para>Dit document is auteursrechtelijk beschermd (c) 2002 door 
      Norman Patten. Het is toegestaan dit document te kopi&euml;ren,
      distribueren en/of aan te passen onder de voorwaarden
      van de GNU Free Documentation Licence, versie 1.1 of enige latere
      versie gepubliceerd door de Free Software Foundation;
      zonder Invariant secties, zonder Front-Cover
      teksten, en zonder Back-Cover teksten. Een kopie van de licentie is
      beschikbaar op <ulink url="http://www.gnu.org/copyleft/fdl.html">
      http://www.gnu.org/copyleft/fdl.html</ulink>. </para>

      <para>Linux is een geregistreerd handelsmerk van Linus Torvalds .
      lkcd is gedistribueerd onder het copyright van Silicon Graphics Inc. </para>

      <para>Stuur feedback naar
      <ulink url="mailto:nepatten@us.ibm.com"><citetitle>nepatten@us.ibm.com</citetitle></ulink>.
      </para>
    </sect2>
  </sect1>

  <sect1 id="howitworks"><title>Hoe LKCD werkt</title>
    <para>
    Wanneer een kernel bepaalde fouten tegenkomt, roept het de
    &quot;panic&quot; functie aan wat resulteert in een onherstelbare
    fout. Deze panic geeft als resultaat dat LKCD een kerneldump initieert
    waarbij kernelgeheugen wordt gekopieerd naar een vooraf toegekend 
    dumpgebied. Het dump device wordt standaard als primair swap geconfigureerd.
    De kernel is nu niet volledig functioneel, maar er is
    voldoende functionaliteit over voor het kopi&euml;ren van het
    geheugen naar disk. Nadat dump het kopi&uml;ren van geheugen naar disk
    heeft voltooid, wordt het systeem opnieuw opgestart.
    Tijdens de nieuwe systeemstart
    controleert het op een nieuwe crash dump. Wanneer een
    nieuwe crash dump wordt aangetroffen, wordt het vanuit de dump lokatie
    gekopieerd naar het bestandssysteem
    standaard de &quot;<filename>/var/log/dump</filename>&quot; directory.
    Na het kopi&euml;ren van het image, gaat het systeem normaal verder 
    met het bootproces en kan onderzoek op een later tijdstip plaatsvinden.
    </para>

    <sect2 id="whatyouneed"><title>Wat je nodig hebt</title>
      <para>
      Het bestand <filename>lkcd-kernelxxx.diff</filename> voor het
      patchen van de kernel. De ondersteunde kernelversie zal
      volgens vaste regel wijzigen.
      <filename>lkcdutils-xx.src.rpm</filename> - dit is de broncode
      van de utility's en de scripts die je nodig hebt om een crash
      in te stellen en te lezen. Op moment van schrijven
      is een rpm binary voor de i386'r beschikbaar vanaf
      <ulink url="http://lkcd.sourceforge.net/">lkcd.sourceforge.net</ulink>, 
      maar je zult nog steeds de patches nodig hebben voor de opstartscripts
      vanuit de rpm broncode.
      </para>
    </sect2>
  </sect1>

  <sect1 id="install"><title>Installatie van lkcd</title>

    <sect2><title>Installeren vanuit broncode</title>
      <para>
      Haal het bestand <filename>lkcdutils-xxx.src.rpm</filename> op en
      installeer het met <command>rpm -i kcdutils-xxx.src.rpm</command> .
      Een bestand met de naam <filename>lkcdutils-xxx.tar.gz</filename> zal
      worden geplaatst in de directory
      <filename>/usr/src/redhat/SOURCES</filename>. Dit
      bestand is een gecomprimeerd tar image van de lkcd broncodestructuur.
      Pak de broncode uit in een directory naar keuzen zoals
      &quot;<filename>/usr/src</filename>&quot; met 
      <command>tar -zxvf kcdutils-xxx.src.rpm</command> . 
      Er zal nu een directory genaamd
      &quot;<filename>kcdutils-xxx</filename>&quot; worden aangemaakt
      met de broncode van de LKCD utility's.
      </para>
    </sect2> 

    <sect2><title>Bouwen en installeren van de LKCD utility's</title>
      <para>
      LKCD gebruikte de standaard GCC compiler en make files. Voor
      het bouwen van de suite, cd je naar de LKCD src directory en
      start <command>./configure</command> om de configuratiebestanden
      te configureren. De volgende stap bestaat uit de uitvoering van
      <command>make</command> om de utility's te compileren
      en tenslotten uit het opstarten van <command>make install</command>
      om de utility's en de manpages te installeren.
      </para>
    </sect2> 

    <sect2><title>Wat wordt er ge&iuml;nstalleerd</title>
      <screen>
  /etc/sysconfig/dump             # Configuratiebestand voor dump
  /sbin/lcrash                    # Het crash utility
  /sbin/lkcd                      # Script om een crash te configureren en
                                  # op te slaan
  /sbin/lkcd_config               # Configuratie-utility voor dump
  /sbin/lkcd_ksyms                # Utility voor het reconstrueren van 
                                  # kernel symbolen 
  /usr/include/sial_api.h         # Header file voor de SIAL API
  /usr/lib/libsial.a              # Simple Image Access Language library
  /usr/man/man1/lcrash.1          # man page voor lcrash
  /usr/man/man1/lkcd_config.1     # man page voor lkcd_config
  /usr/man/man1/lkcd_ksyms.1      # man page voor lkcd_ksyms
  /usr/share/sial/lcrash/ps.sial  # ps opdracht implementatie van SIAL
      </screen>
    </sect2>

    <sect2><title>Installeren van de LKCD utility's vanuit een RPM</title>
      <para>
      Je kunt voorgecompileerde utility's van rpm installeren met
      <command>rpm -i kcdutils-xxx.rpm</command> . Je zult nog steeds de
      kernel moeten patchen en de patches voor de opstartscripts moeten
      installeren. Je kunt echter het compileren van de utility's overslaan.
      </para>
    </sect2>

    <sect2><title>Patchen van de kernel</title>
      <para>
      De volgende stap bestaat uit het patchen en hercompileren van de kernel.
      Je zult de broncode van de kernel moeten patchen met het
      <filename>lkcd-xxx.diff</filename> bestand dat je downloadde vanaf
      <ulink url="http://lkcd.sourceforge.net/">http://lkcd.sourceforge.net/</ulink>.
      Kopieer de patch naar dezelfde directory als je kernel en geef de opdracht
      <command>patch -p0 &lt; lkcd-kernelxxx.diff</command>. Zorg dat
      de patch dezelfde versie heeft als de kernel die je gaat patchen.
      Vervolgens zul je de kernel moeten configureren om de crash dump
      ondersteuning te activeren. Standaard is de crash ondersteuning uitgezet
      na toepassing van de patch. Als je <command>make menuconfig</command>
      of <command>make xconfig</command> gebruikt, is de optie
      &quot;LKCD support&quot; te vinden onder kernel hacking.
      Wellicht dat je ook nog andere
      kernelfeatures moet activeren die je nodig hebt. Zie de 
      <ulink url="http://linuxdoc.org/HOWTO/Kernel-HOWTO.html">Linux 
      Kernel HOWTO</ulink> voor meer details. </para>
    </sect2>

    <sect2><title>Compileer en installeer de kernel</title>
      <para>
      De volgende stap bestaat uit het compileren en installeren van
      de met crash geactiveerde kernel. Start in onderstaande volgorde
      de volgende opdrachten op vanuit de directory met kernel bronbestanden.
      </para>
      <screen> 
  make depend 
  make install 
  make modules
  make modules_install
      </screen>
      <para>
      Hiermee zal de nieuwe kernel worden gecompileerd en ge&iuml;nstalleerd.
      Je moet ook het bestand <filename>Kerntypes</filename> vanuit de
      directory met kernbroncode kopi&euml;ren naar de 
      <filename>/boot</filename> directory. Wellicht dat je ook
      nog het bestand <filename>lilo.conf</filename> moet wijzigen zodat er
      in wordt verwezen naar je nieuwe kernel. Zie
<ulink url="http://linuxdoc.org/HOWTO/Kernel-HOWTO.html">http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html</ulink>
      voor meer informatie over het compileren en installeren van een kernel.
     </para>
    </sect2>
  </sect1>

  <sect1 id="setup"><title>Setup, test, en het uitvoeren van crash</title>

    <sect2><title>Instellen van crash dump</title>
      <para>
      Om een core image te kunnen bewaren dat naar swap is geschreven,
      moet het image worden opgeslagen voordat de swap tijden het
      booten wordt gemount. Hiervoor moet het opstartbestand
      <filename>sysinit</filename> worden gewijzigd.
      In de broncode van lkcd is een
      <filename>scripts</filename> directory opgenomen waarin de patches
      staan voor diverse sysinit opstartscripts. Deze patches voegen de
      <command>lkcd config</command> en <command>lkcd save</command>
      opdrachten toe om crash dumps te activeren en een eventuele
      bestaande crash dump bij het opstarten op te slaan.
      </para>
    </sect2>

    <sect2><title>Testen van crash</title>
      <para>
      Om een panic te forceren zodat je de nieuwe crash setup kunt testen,
      compileer je de volgende code met
      <command>cc -c -I/usr/src/linux/include panic.c</command> . 
      Na het bouwen van de <filename>panic.o</filename> module geef je de
      opdracht <command>insmod panic.o</command> om een kernel panic
      te activeren.</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>Uitvoeren van crash</title>
      <para>
      Om je kernel core file te kunnen bekijken moet <command>lcrash</command> 
      worden aangeroepen met een paar parameters:
      </para>
      <screen>
  <command>lcrash [ System.map file ] [ dump image ] [ Kerntypes ]</command>

  Voorbeeld:

  <command>lcrash /boot/System.map ./dump.1 /boot/Kerntypes</command>
      </screen>
      <para>Het zal even duren eer het kernelimage in het geheugen is geladen
      en het je dropt in de crash shell. Achter de crash shellprompt kun je
      een <userinput>?</userinput> intikken voor een overzicht met de 
      beschikbare opdrachten.</para>
    </sect2>
  </sect1>
 </article>

