Author: ug Date: Tue Nov 25 12:40:35 2008 New Revision: 53570 URL: http://svn.opensuse.org/viewcvs/yast?rev=53570&view=rev Log: kdump docu added Modified: trunk/autoinstallation/doc/CreateProfileDetails.xml trunk/autoinstallation/package/autoyast2.changes Modified: trunk/autoinstallation/doc/CreateProfileDetails.xml URL: http://svn.opensuse.org/viewcvs/yast/trunk/autoinstallation/doc/CreateProfileDetails.xml?rev=53570&r1=53569&r2=53570&view=diff ============================================================================== --- trunk/autoinstallation/doc/CreateProfileDetails.xml (original) +++ trunk/autoinstallation/doc/CreateProfileDetails.xml Tue Nov 25 12:40:35 2008 @@ -2504,6 +2504,561 @@ </section> </section> + <!-- {{{ Kdump --> + + <section id="CreateProfile.kdump"> + <title> + Kernel dumps + </title> + + <note> + This feature is only available since openSUSE 11.1 and SLES 11. It is not available + on the <emphasis>zSeries</emphasis> (<emphasis>s390x</emphasis>) architecture! + </note> + + <para> + With kdump the system is able to create crashdump files if the whole system (i.e., the + kernel) crashes. That crash dump files contain the memory contents while the system crashed. + Such core files can be analyzed later by the support or a (kernel) developer to find the + reason why the system crashed. It's mostly useful for servers where you cannot + easily reproduce such crashes on another system and where it's important that the + problem gets fixed. + </para> + + <para> + The only downside of enabling kdump is that this costs you between 64 MiB and + 128 MiB of System RAM (on "normal" sized systems) that needs to be reserved to + be used by kdump in the case the system crashes and the dump needs to be generated. + </para> + + <para>This section only describes how to setup kdump with &autoyast;. It does not describe + how kdump works in general and also does not describe each small detail. Refer to + the kdump(7) manual page which is in the package named <emphasis>kdump</emphasis> or to + the <ulink url="http://en.opensuse.org/Kdump">openSUSE Kdump documentation</ulink>. + </para> + + <para> + At first, let's present an overall example for the kdump configuration: + </para> + + &example.kdump; + + <!-- {{{ Memory Reservation --> + <section id="CreateProfile.kdump.reservation"> + <title>Memory Reservation</title> + + <para> + As already mentioned above, it's necessary to reserve some memory at bootup for + kdump. Because that memory must be reserved very early during the boot process, + the configuration is done via a kernel command line parameter called + <literal>crashkernel</literal>. That memory will be used to load a second kernel + in that memory that will be executed without rebooting if the first kernel + crashes. That kernel also has a special initrd which contains all programs + that are necessary to save the dump to network or disk, send the notification + email and finally reboot. + </para> + + <para> + You can enable or disable that the <literal>crashkernel</literal> parameter is + written for the default boot kernel with the <literal>add_crash_kernel</literal> + tag and you can specify the value of the <literal>crashkernel</literal> parameter + using the <literal>crash_kernel</literal> tag. + </para> + + <para> + For the memory reservation there are two things to specify: The <emphasis>amount</emphasis> + of reserved memory (such as <literal>64M</literal> to reserve 64 MiB of memory from + the RAM) and the <emphasis>offset</emphasis>. The syntax is + <literal>crashkernel=AMOUNT@OFFSET</literal>. Luckily the kernel is able to auto-detect the + right offset for you nowadays (with the exception of the Xen hypervisor where you have to + specify <emphasis>16M</emphasis> as offset), so you don't have to worry about that too much. + You can just specify <literal><crash_kernel>crashkernel=64M</crash_kernel></literal> + and the right thing will happen. + </para> + + <para> + For the <emphasis>amount</emphasis> of memory, following values are recommended: + </para> + + <para> + <table frame="top"> + <title>Recommended values for the reserved memory amount</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Platform</entry> + <entry>Recommended values</entry> + </row> + </thead> + <tbody> + <row> + <entry> + i386 and x86-64 + </entry> + <entry> + <literal>64M</literal> for small machines (about 2 GiB of RAM, 4 cores) + and <literal>128M</literal> for larger machines + </entry> + </row> + </tbody> + <tbody> + <row> + <entry> + PPC64 + </entry> + <entry> + <literal>128M</literal> for small machines + and <literal>256M</literal> for larger machines + </entry> + </row> + </tbody> + <tbody> + <row> + <entry> + IA64 + </entry> + <entry> + <literal>256M</literal> for small machines, + <literal>512M</literal> for medium machines and + <literal>1G</literal> and more for really large machines + (mostly SGI Altix systems) + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + <para> + To make things even more complicated, there's a so-called <emphasis>extended + command line syntax</emphasis> where you can specify the amount of reserved + memory dependent of the System RAM. That is good if you share one &autoyast; + profile for multiple installations or when you often remove or install memory + on one machine. The syntax is: + </para> + + <para> + <screen>BEGIN_RANGE_1-END_RANGE_1:AMOUNT_1,BEGIN_RANGE_2-END_RANGE_2:AMOUNT_2@OFFSET</screen> + </para> + + <para> + In that syntax <literal>BEGIN_RANGE_1</literal> is the start of the first + memory range (for example: <literal>0M</literal>) and <literal>END_RANGE_1</literal> + is the end of the first memory range (and can be empty in case "infinity" should + be assumed) and so on. So for example + <literal>256M-2G:64M,2G-:128M</literal> means to reserve 64 MiB of crashkernel + memory when the system has between 256 MiB and 2 GiB RAM and to reserve + 128 MiB of crashkernel memory when the system has above 2 GiB RAM. + </para> + + <para> + The following table contains the settings that are necessary for the + memory reservation: + </para> + + <para> + <table frame='top'> + <title>XML representation of the memory reservation settings</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Element</entry> + <entry>Description</entry> + <entry>Comment</entry> + </row> + </thead> + <tbody> + <row> + <entry>add_crash_kernel</entry> + <entry>If the memory should be reserved, that basically enables or disables kdump. + <para><screen><add_crash_kernel config:type="boolean">true</add_crash_kernel></screen></para></entry> + <entry>required</entry> + </row> + <row> + <entry>crash_kernel</entry> + <entry>The syntax of the crashkernel command line as discussed above. + <para><screen><crash_kernel>256M:64M</crash_kernel></screen></para></entry> + <entry>required</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </section> + <!-- }}} --> + <!-- {{{ Dump Saving --> + <section id="CreateProfile.kdump.saving"> + <title> + Dump Saving + </title> + + <!-- {{{ Target --> + <section id="CreateProfile.kdump.saving.target"> + <title> + Target + </title> + + <para> + The element <literal>KDUMP_SAVEDIR</literal> holds an URL to where the dump + is saved. Following methods are possible: + </para> + + <itemizedlist mark='opencircle'> + <listitem> + <para> + <literal>file</literal> to save to the local disk + </para> + </listitem> + <listitem> + <para> + <literal>ftp</literal> to save to an FTP server (without encryption) + </para> + </listitem> + <listitem> + <para> + <literal>sftp</literal> to save to an SSH2 SFTP server + </para> + </listitem> + <listitem> + <para> + <literal>nfs</literal> to save to a NFS location and + </para> + </listitem> + <listitem> + <para> + <literal>cifs</literal> to save the dump to a CIFS/SMP export from Samba or Microsoft Windows. + </para> + </listitem> + </itemizedlist> + + <para> + For details see the kdump(5) manual page. Two examples are: + <literal>file:///var/crash</literal> (which is the default location + according to FHS) and <literal>ftp://user:password@host:port/incoming/dumps</literal>. + Below that directory, a directory name that contains a time stamp will be created + in which the dumps are saved. + </para> + + <para> + When the dump is saved to the local disk, <literal>KDUMP_KEEP_OLD_DUMPS</literal> + can be used to delete old dumps automatically. This setting takes a number that + specifies how much old dumps should be kept. If the partition has less than + <literal>KDUMP_FREE_DISK_SIZE</literal> megabytes free disk space after saving the + dump, the dump is not copied at all. + </para> + + <para> + If you would not like only to save the dump but also the whole kernel and + (if installed) the debug information of the kernel to that directory to have + everything you need (except all kernel modules and the debugging information + of all kernel modules) to analyze the dump in one directory, you can set + <literal>KDUMP_COPY_KERNEL</literal> to <literal>true</literal>. + </para> + </section> + <!-- }}} --> + <!-- {{{ Filtering and Compression --> + <section id="CreateProfile.kdump.saving.compression"> + <title> + Filtering and Compression + </title> + + <para> + The size of kernel dumps is uncompressed and unfiltered as large as your system has RAM. + To get smaller files (for example, to send it to support), you can compress the whole + dump file afterwards. However, the drawback is that the dump has to be uncompressed + afterwards before opening, so the disk space needs to be there in any case. + </para> + + <para> + To use page compression which compresses every page and allows dynamic decompression + with the crash(8) debugging tool, set <literal>KDUMP_DUMPFORMAT</literal> to + <literal>compressed</literal> (which is actually the default). + </para> + + <para> + To filter the dump, you have to set the <literal>KDUMP_DUMPLEVEL</literal>. Then not all + memory is saved to disk but only memory that does not fulfill some criteria. I.e. you + may want to leave out pages that are completely filled by zeroes as they don't + contain any useful information. 0 produces a full dump and 31 is the smallest dump. + The manual page kdump(5) and makedumpfile(8) contain a table that lists for + each value which pages will be saved. + </para> + + </section> + <!-- }}} --> + <!-- {{{ Table --> + <section id="CreateProfile.kdump.saving.summary"> + <title> + Summary + </title> + <para> + <table frame='top'> + <title>XML representation of the dump target settings</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Element</entry> + <entry>Description</entry> + <entry>Comment</entry> + </row> + </thead> + <tbody> + <row> + <entry>KDUMP_SAVEDIR</entry> + <entry>An URL that specifies the target to which the dump and related files will be saved. + <para><screen><KDUMP_SAVEDRIR>file:///var/crash/</KDUMP_SAVEDIR></screen></para></entry> + <entry>required</entry> + </row> + <row> + <entry>KDUMP_COPY_KERNEL</entry> + <entry>If not only the dump itself should be saved to <literal>KDUMP_SAVEDIR</literal> but + also the kernel and its debugging information (if installed). + <para><screen><KDUMP_COPY_KERNEL>false</KDUMP_COPY_KERNEL></screen></para></entry> + <entry>optional</entry> + </row> + <row> + <entry>KDUMP_FREE_DISK_SIZE</entry> + <entry> + The number of megabytes that should always be free after saving the dump. If that + space would be below that value, the dump will not be copied. + <para><screen><KDUMP_FREE_DISK_SIZE>64</KDUMP_FREE_DISK_SIZE></screen></para></entry> + <entry>optional</entry> + </row> + <row> + <entry>KDUMP_KEEP_OLD_DUMPS</entry> + <entry> + The number of dumps that are kept (i.e., not deleted) if <literal>KDUMP_SAVEDIR</literal> + points to a local directory. Specify 0 if you don't want to delete dumps at all and + specify -1 if all dumps (except the one that is just saved) should be deleted. + <para><screen><KDUMP_KEEP_OLD_DUMPS>4</KDUMP_KEEP_OLD_DUMPS></screen></para></entry> + <entry>optional</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </section> + <!-- }}} --> + + </section> + <!-- }}} --> + <!-- {{{ Email Notification --> + <section id="CreateProfile.kdump.notification"> + <title> + Email Notification + </title> + + <para> + It's useful to get notified via email that a machine has crashed and a dump has been + saved. That way you can for example setup a dump server in a company and trigger + some actions by that email automatically like calling the administrator from home + to check if everything runs again. + </para> + + <para> + Because the dump is saved in a special initrd environment, we cannot use a local + mail server just to send that notification email. However, it's better to send + that email in the initrd just because it's more likely that we have a working network + connection here (which we need in the netdump case to save the dump away anyway) + compared that the server comes up again and everything is working. + </para> + + <para>You have to provide at least exactly one address in + <literal>KDUMP_NOTIFICATION_TO</literal> and zero, one or more addresses + in <literal>KDUMP_NOTIFICATION_CC</literal>. Please note that you can only + specify the address here, not a real name or some other fancy stuff. + </para> + + <para> + To actually send the email, we need <literal>KDUMP_SMTP_SERVER</literal> and + (if the server needs authentication) <literal>KDUMP_SMTP_USER</literal> and + <literal>KDUMP_SMTP_PASSWORD</literal>. Please note that TSL or SSL are not supported. + That may be added in future. + </para> + + <para> + <!-- {{{ Table: XML representation of the email notification settings --> + <table frame='top'> + <title>XML representation of the email notification settings</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Element</entry> + <entry>Description</entry> + <entry>Comment</entry> + </row> + </thead> + <tbody> + <row> + <entry>KDUMP_NOTIFICATION_TO</entry> + <entry>Exactly one email address (and only an address) to which the mail + should be sent. Additional recipients can be specified in + <literal>KDUMP_NOTIFICATION_CC</literal>. + <para><screen><KDUMP_NOTIFICATION_TO>bwalle@suse.de</KDUMP_NOTIFICATION_TO></screen></para></entry> + <entry>optional (email notification is disabled if empty)</entry> + </row> + <row> + <entry>KDUMP_NOTIFICATION_CC</entry> + <entry>Zero, one or more recipients that are in the Cc line of the notification mail. + <para><screen><KDUMP_NOTIFICATION_CC>spam@suse.de devnull@suse.de</KDUMP_NOTIFICATION_CC></screen></para></entry> + <entry>optional</entry> + </row> + <row> + <entry>KDUMP_SMTP_SERVER</entry> + <entry> + Host name of the SMTP server that will be used for the mail delivery. Please note + that the SMTP authentication is supported (see <literal>KDUMP_SMTP_USER</literal> + and <literal>KDUMP_SMTP_PASSWORD</literal>) but TSL and SSL are <emphasis>not</emphasis> + supported. + <para><screen><KDUMP_SMTP_SERVER>email.suse.de</KDUMP_SMTP_SERVER></screen></para></entry> + <entry>optional (email notification is disabled if empty)</entry> + </row> + <row> + <entry>KDUMP_SMTP_USER</entry> + <entry> + User name that is used together with <literal>KDUMP_SMTP_PASSWORD</literal> + for SMTP authentication. + <para><screen><KDUMP_SMTP_USER>bwalle</KDUMP_SMTP_USER></screen></para></entry> + <entry>optional</entry> + </row> + <row> + <entry>KDUMP_SMTP_PASSWORD</entry> + <entry> + Password that is used together with <literal>KDUMP_SMTP_USER</literal> + for SMTP authentication. + <para><screen><KDUMP_SMTP_PASSWORD>geheim</KDUMP_SMTP_PASSWORD></screen></para></entry> + <entry>optional</entry> + </row> + </tbody> + </tgroup> + </table> + <!-- }}} --> + </para> + </section> + <!-- }}} --> + <!-- {{{ Kdump kernel settings --> + <section id="CreateProfile.kdump.kernel"> + <title> + Kdump kernel settings + </title> + + <para> + As already mentioned, a special kernel is booted to save the dump. + If you don't want to use the auto-detection mechanism to find out which kernel + is used (see the kdump(5) manual page that describes the algorithm which + is used to find the kernel), you can specify the version of a custom kernel + in <literal>KDUMP_KERNELVER</literal>. If you set that to + <literal>foo</literal>, then the kernel located in + <filename>/boot/vmlinuz-foo</filename> or <filename>/boot/vmlinux-foo</filename> + (in that order on platforms that have a <filename>vmlinuz</filename> file) + will be used. + </para> + + <para> + You can even specify the command line which will be used to boot the kdump kernel. + Normally the boot command line is used minus some settings that hurt in the + kdump case (like the <literal>crashkernel</literal> parameter itself) plus + some settings that are needed in the kdump case (see the manual page kdump(5)). + If you just want some additional parameters like a overwritten console setting + then use <literal>KDUMP_COMMANDLINE_APPEND</literal>. If you know what you're doing + and you want to specify the whole command line, set <literal>KDUMP_COMMANDLINE</literal>. + </para> + + <para> + <!-- {{{ Table: XML representation of the kernel settings --> + <table frame='top'> + <title>XML representation of the kernel settings</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Element</entry> + <entry>Description</entry> + <entry>Comment</entry> + </row> + </thead> + <tbody> + <row> + <entry>KDUMP_KERNELVER</entry> + <entry>Version string for the kernel that will be used for kdump. Leave it + empty to use the auto-detection mechanism (strongly recommended). + <para><screen><KDUMP_KERNELVER>2.6.27-default</KDUMP_KERNELVER></screen></para></entry> + <entry>optional (auto-detection if empty)</entry> + </row> + <row> + <entry>KDUMP_COMMANDLINE_APPEND</entry> + <entry>Additional command line parameters for the kdump kernel. + <para><screen><KDUMP_COMMANDLINE_APPEND>console=ttyS0,57600</KDUMP_COMMANDLINE_APPEND></screen></para></entry> + <entry>optional</entry> + </row> + <row> + <entry>KDUMP_COMMANDLINE</entry> + <entry> + Overwrite the automatically generated kdump command line. Use with care. + Normally <literal>KDUMP_COMMANDLINE_APPEND</literal> is the setting you're + looking for. + <para><screen><KDUMP_COMMANDLINE_APPEND>root=/dev/sda5 maxcpus=1 irqpoll</KDUMP_COMMANDLINE></screen></para></entry> + <entry>optional (email notification is disabled if empty)</entry> + </row> + </tbody> + </tgroup> + </table> + <!-- }}} --> + </para> + </section> + <!-- }}} --> + <!-- {{{ Expert settings --> + <section id="CreateProfile.kdump.expert"> + <title> + Expert settings + </title> + + <para> + <!-- {{{ Table: XML representation of the expert settings --> + <table frame='top'> + <title>XML representation of the expert settings</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Element</entry> + <entry>Description</entry> + <entry>Comment</entry> + </row> + </thead> + <tbody> + <row> + <entry>KDUMP_IMMEDIATE_REBOOT</entry> + <entry><literal>true</literal> if the system should be rebooted automatically + after the dump has been saved, <literal>false</literal> otherwise. The default + is to reboot the system automatically. + <para><screen><KDUMP_IMMEDIATE_REBOOT>true</KDUMP_IMMEDIATE_REBOOT></screen></para></entry> + <entry>optional</entry> + </row> + <row> + <entry>KDUMP_VERBOSE</entry> + <entry>Bitmask that specifies how to verbose the kdump process should be. + Read kdump(5) for details. + <para><screen><KDUMP_VERBOSE>3</KDUMP_VERBOSE></screen></para></entry> + <entry>optional</entry> + </row> + <row> + <entry>KEXEC_OPTIONS</entry> + <entry>Additional options that are passed to <application>kexec</application> + when loading the kdump kernel. Normally empty. + <para><screen><KEXEC_OPTIONS>--noio</KEXEC_OPTIONS></screen></para></entry> + <entry>optional</entry> + </row> + </tbody> + </tgroup> + </table> + <!-- }}} --> + </para> + + </section> + <!-- }}} --> + + </section> + <!-- }}} --> + <section id="CreateProfile.Ask"> <title> Ask the user for values during installation Modified: trunk/autoinstallation/package/autoyast2.changes URL: http://svn.opensuse.org/viewcvs/yast/trunk/autoinstallation/package/autoyast2.changes?rev=53570&r1=53569&r2=53570&view=diff ============================================================================== --- trunk/autoinstallation/package/autoyast2.changes (original) +++ trunk/autoinstallation/package/autoyast2.changes Tue Nov 25 12:40:35 2008 @@ -1,4 +1,9 @@ ------------------------------------------------------------------- +Tue Nov 25 12:39:39 CET 2008 - ug@suse.de + +- kdump documentation by bwalle added + +------------------------------------------------------------------- Mon Nov 24 14:12:23 CET 2008 - ug@suse.de - switch for installation of recommended patterns added -- To unsubscribe, e-mail: yast-commit+unsubscribe@opensuse.org For additional commands, e-mail: yast-commit+help@opensuse.org