Author: emap Date: Sun Nov 6 18:26:08 2011 New Revision: 66729 URL: http://svn.opensuse.org/viewcvs/yast?rev=66729&view=rev Log: edited by emap Modified: trunk/autoinstallation/doc/xml/KDumpSection.xml Modified: trunk/autoinstallation/doc/xml/KDumpSection.xml URL: http://svn.opensuse.org/viewcvs/yast/trunk/autoinstallation/doc/xml/KDumpSection.xml?rev=66729&r1=66728&r2=66729&view=diff ============================================================================== --- trunk/autoinstallation/doc/xml/KDumpSection.xml (original) +++ trunk/autoinstallation/doc/xml/KDumpSection.xml Sun Nov 6 18:26:08 2011 @@ -25,36 +25,34 @@ </title> <note> - <title>FIXME Title</title> + <title>FIXME Title</title><remark>emap 2011-11-06: Add title, maybe: Availability?</remark> <para> This feature is only available since SLES 11 (not openSUSE 11.1). It is not available - on the <emphasis>zSeries</emphasis> (<emphasis>s390x</emphasis>) architecture! + on the <emphasis>zSeries</emphasis> (<emphasis>s390x</emphasis>) architecture. </para> </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. + kernel) crashes. Crash dump files contain the memory contents while the system crashed. + Such core files can be analyzed later by support or a (kernel) developer to find the + reason for the system crash. Kdump is mostly useful for servers where you cannot + easily reproduce such crashes but it is important to get the + problem 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. + The only downside: enabling kdump costs you between 64 MiB and + 128 MiB of system RAM (on "normal" sized systems), reserved for kdump in 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>This section only describes how to set up kdump with &ay;. It does not describe + how kdump works. For details, refer to + the kdump(7) manual page, contained in the <emphasis>kdump</emphasis> package, or to <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: + The following example shows a general kdump configuration. </para> &example.kdump; @@ -64,36 +62,37 @@ <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. + The first step is to reserve memory for kdump at boot-up. Because the + memory must be reserved very early during the boot process, the + configuration is done via a kernel command line parameter called + <literal>crashkernel</literal>. The reserved memory will be used to + load a second kernel which will be executed without rebooting if the + first kernel crashes. This second kernel has a special initrd, which + contains all programs necessary to save the dump over the network or + to disk, send a notification e-mail, 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. + Enable or disable that the <literal>crashkernel</literal> + parameter is written for the default boot kernel with the + <literal>add_crash_kernel</literal> tag. You can specify the value + of the <literal>crashkernel</literal> parameter using the + <literal>crash_kernel</literal> tag.<remark>emap 2011-11-06: Does this para make sense? Seems a bit obscure.</remark> </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 + To reserve memory for kdump, specify the <emphasis>amount</emphasis> + (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> + <literal>crashkernel=AMOUNT@OFFSET</literal>. The kernel can auto-detect the + right offset (with the exception of the Xen hypervisor, where you have to + specify <emphasis>16M</emphasis> as offset). + Simply 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: + For the <emphasis>amount</emphasis> of memory, the following values are recommended: </para> <table frame="top"> @@ -140,32 +139,31 @@ </table> <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 + You can also use the <emphasis>extended + command line syntax</emphasis> to specify the amount of reserved + memory depending on the System RAM. That is useful if you share one &ay; + profile for multiple installations or if you often remove or install memory on one machine. The syntax is: </para> <screen>BEGIN_RANGE_1-END_RANGE_1:AMOUNT_1,BEGIN_RANGE_2-END_RANGE_2:AMOUNT_2@OFFSET</screen> <para> - In that syntax <literal>BEGIN_RANGE_1</literal> is the start of the first + <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 + is the end of the first memory range (can be empty in case "infinity" should + be assumed) and so on. 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. + memory if the system has between 256 MiB and 2 GiB RAM and to reserve + 128 MiB of crashkernel memory if the system has more than 2 GiB RAM. </para> <para> - The following table contains the settings that are necessary for the - memory reservation: + The following table shows the settings necessary to reserve memory: </para> <table frame='top'> - <title>XML representation of the memory reservation settings</title> + <title>XML Representation of the Memory Reservation Settings</title> <tgroup cols="3"> <thead> <row> @@ -177,13 +175,13 @@ <tbody> <row> <entry>add_crash_kernel</entry> - <entry><para>If the memory should be reserved, that basically enables or disables kdump. + <entry><para>Set to "true" if memory should be reserved and kdump enabled. </para><screen><add_crash_kernel config:type="boolean">true</add_crash_kernel></screen></entry> <entry>required</entry> </row> <row> <entry>crash_kernel</entry> - <entry><para>The syntax of the crashkernel command line as discussed above. + <entry><para>Use the syntax of the crashkernel command line as discussed above. </para><screen><crash_kernel>256M:64M</crash_kernel></screen></entry> <entry>required</entry> </row> @@ -206,24 +204,24 @@ </title> <para> - The element <literal>KDUMP_SAVEDIR</literal> holds an URL to where the dump - is saved. Following methods are possible: + The element <literal>KDUMP_SAVEDIR</literal> specifies the URL to + where the dump is saved. The following methods are possible: </para> <itemizedlist mark='opencircle'> <listitem> <para> - <literal>file</literal> to save to the local disk + <literal>file</literal> to save to the local disk, </para> </listitem> <listitem> <para> - <literal>ftp</literal> to save to an FTP server (without encryption) + <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 + <literal>sftp</literal> to save to an SSH2 SFTP server, </para> </listitem> <listitem> @@ -242,24 +240,25 @@ 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. + A subdirectory, with the time stamp contained in the name, will be created and the dumps saved there. </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. + When the dump is saved to the local disk, + <literal>KDUMP_KEEP_OLD_DUMPS</literal> can be used to delete old + dumps automatically. Set it to the number of old dumps that should + be kept. If the target partition would end up with less free disk + space than specified in <literal>KDUMP_FREE_DISK_SIZE</literal>, the + dump is not saved.<remark>emap 2011-11-06: Replaced 'copied' with + 'saved'.</remark> </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 + If you want to save the whole kernel and the debug + information (if installed) to the same directory, set <literal>KDUMP_COPY_KERNEL</literal> to <literal>true</literal>. + You'll have everything you need to analyze the dump in one directory + (except kernel modules and their debugging information). </para> </section> <!-- }}} --> @@ -270,25 +269,24 @@ </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. + The kernel dump is uncompressed and unfiltered. It can get as + large as your system RAM. To get smaller files, compress the dump file afterwards. The dump has to be + decompressed before opening<!--, so the disk space needs to + be there in any case-->.<remark>emap 2011-11-06: Can we delete this? If the disk space is really smaller than the RAM, it's probably not a smart idea to save the dump on the disk.</remark> </para> <para> - To use page compression which compresses every page and allows dynamic decompression + 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). + <literal>compressed</literal> (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. + You may not want to save all memory pages, for example those filled + with zeroes. To filter the dump, set the + <literal>KDUMP_DUMPLEVEL</literal>. 0 produces a full dump and 31 is + the smallest dump. The manual pages kdump(5) and makedumpfile(8) + list for each value which pages will be saved. </para> </section> @@ -299,7 +297,7 @@ Summary </title> <table frame='top'> - <title>XML representation of the dump target settings</title> + <title>XML Representation of the Dump Target Settings</title> <tgroup cols="3"> <thead> <row> @@ -317,7 +315,7 @@ </row> <row> <entry>KDUMP_COPY_KERNEL</entry> - <entry><para>If not only the dump itself should be saved to <literal>KDUMP_SAVEDIR</literal> but + <entry><para>Set to "true", if not only the dump 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></entry> <entry>optional</entry> @@ -325,8 +323,9 @@ <row> <entry>KDUMP_FREE_DISK_SIZE</entry> <entry> - <para>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>Disk space in megabytes that must remain free after + saving the dump. If not enough space is available to write the dump and keep the required disk space free, the + dump will not be saved. </para><screen><KDUMP_FREE_DISK_SIZE>64</KDUMP_FREE_DISK_SIZE></screen></entry> <entry>optional</entry> </row> @@ -334,8 +333,7 @@ <entry>KDUMP_KEEP_OLD_DUMPS</entry> <entry> <para>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. + points to a local directory. Specify 0 if you do not want any dumps to be automatically deleted, specify -1 if all dumps except the current one should be deleted. </para><screen><KDUMP_KEEP_OLD_DUMPS>4</KDUMP_KEEP_OLD_DUMPS></screen></entry> <entry>optional</entry> </row> @@ -354,36 +352,29 @@ </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. + Configure email notification, if you want to be informed when a machine crashes and a dump is saved. </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. + Because kdump runs in the initrd, a local + mail server cannot send the notification email. An SMTP server needs to be specified (see below).<remark>emap 2011-11-06: Removed major section that didn't make sense. Please check if my changes here are correct.</remark> </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>You have to provide exactly one address in + <literal>KDUMP_NOTIFICATION_TO</literal>. More addresses can be specified in + in <literal>KDUMP_NOTIFICATION_CC</literal>. Only + use email addresses in both cases, not a real name. </para> <para> - To actually send the email, we need <literal>KDUMP_SMTP_SERVER</literal> and + Specify <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. + <literal>KDUMP_SMTP_PASSWORD</literal>. Support for TSL or SSL is not available but may be added in the future. </para> <!-- {{{ Table: XML representation of the email notification settings --> <table frame='top'> - <title>XML representation of the email notification settings</title> + <title>XML Representation of the Email Notification Settings</title> <tgroup cols="3"> <thead> <row> @@ -397,32 +388,30 @@ <entry>KDUMP_NOTIFICATION_TO</entry> <entry> <para> - Exactly one email address (and only an address) to which the mail + Exactly one email address to which the email 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></entry> - <entry>optional (email notification is disabled if empty)</entry> + </para><screen><KDUMP_NOTIFICATION_TO>bwalle@suse.de</KDUMP_NOTIFICATION_TO></screen></entry><remark>emap 2011-11-06: Do we really want to use an actual email address here?</remark> + <entry>optional (notification disabled if empty)</entry> </row> <row> <entry>KDUMP_NOTIFICATION_CC</entry> - <entry><para>Zero, one or more recipients that are in the Cc line of the notification mail. + <entry><para>Zero, one or more recipients that are in the cc line of the notification email. </para><screen><KDUMP_NOTIFICATION_CC>spam@suse.de devnull@suse.de</KDUMP_NOTIFICATION_CC></screen></entry> <entry>optional</entry> </row> <row> <entry>KDUMP_SMTP_SERVER</entry> <entry><para> - 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. + Host name of the SMTP server used for mail delivery. SMTP authentication is supported (see <literal>KDUMP_SMTP_USER</literal> + and <literal>KDUMP_SMTP_PASSWORD</literal>) but TSL and SSL are <emphasis>not</emphasis>. </para><screen><KDUMP_SMTP_SERVER>email.suse.de</KDUMP_SMTP_SERVER></screen></entry> - <entry>optional (email notification is disabled if empty)</entry> + <entry>optional (notification disabled if empty)</entry> </row> <row> <entry>KDUMP_SMTP_USER</entry> <entry><para> - User name that is used together with <literal>KDUMP_SMTP_PASSWORD</literal> + User name used together with <literal>KDUMP_SMTP_PASSWORD</literal> for SMTP authentication. </para><screen><KDUMP_SMTP_USER>bwalle</KDUMP_SMTP_USER></screen></entry> <entry>optional</entry> @@ -430,7 +419,7 @@ <row> <entry>KDUMP_SMTP_PASSWORD</entry> <entry><para> - Password that is used together with <literal>KDUMP_SMTP_USER</literal> + Password used together with <literal>KDUMP_SMTP_USER</literal> for SMTP authentication. </para><screen><KDUMP_SMTP_PASSWORD>geheim</KDUMP_SMTP_PASSWORD></screen></entry> <entry>optional</entry> @@ -444,7 +433,7 @@ <!-- {{{ Kdump kernel settings --> <section id="CreateProfile.kdump.kernel"> <title> - Kdump kernel settings + Kdump Kernel Settings </title> <para> @@ -452,7 +441,7 @@ 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 + in <literal>KDUMP_KERNELVER</literal>. If you set it 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) @@ -460,10 +449,9 @@ </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)). + You can specify the command line used to boot the kdump kernel. + Normally the boot command line is used minus some settings that make no sense with kdump (like the <literal>crashkernel</literal> parameter) plus + some settings needed by kdump (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>. @@ -471,7 +459,7 @@ <!-- {{{ Table: XML representation of the kernel settings --> <table frame='top'> - <title>XML representation of the kernel settings</title> + <title>XML Representation of the Kernel Settings</title> <tgroup cols="3"> <thead> <row> @@ -483,7 +471,7 @@ <tbody> <row> <entry>KDUMP_KERNELVER</entry> - <entry><para>Version string for the kernel that will be used for kdump. Leave it + <entry><para>Version string for the kernel 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></entry> <entry>optional (auto-detection if empty)</entry> @@ -498,10 +486,9 @@ <entry>KDUMP_COMMANDLINE</entry> <entry><para> Overwrite the automatically generated kdump command line. Use with care. - Normally <literal>KDUMP_COMMANDLINE_APPEND</literal> is the setting you're - looking for. + In most cases, <literal>KDUMP_COMMANDLINE_APPEND</literal> should suffice. </para><screen><KDUMP_COMMANDLINE_APPEND>root=/dev/sda5 maxcpus=1 irqpoll</KDUMP_COMMANDLINE></screen></entry> - <entry>optional (email notification is disabled if empty)</entry> + <entry>optional<!-- (email notification disabled if empty)--></entry><remark>emap 2011-11-06: I don't think the email stuff belongs here.</remark> </row> </tbody> </tgroup> @@ -512,12 +499,12 @@ <!-- {{{ Expert settings --> <section id="CreateProfile.kdump.expert"> <title> - Expert settings + Expert Settings </title> <!-- {{{ Table: XML representation of the expert settings --> <table frame='top'> - <title>XML representation of the expert settings</title> + <title>XML Representation of the Expert Settings</title> <tgroup cols="3"> <thead> <row> @@ -537,7 +524,7 @@ </row> <row> <entry>KDUMP_VERBOSE</entry> - <entry><para>Bitmask that specifies how to verbose the kdump process should be. + <entry><para>Bitmask that specifies how verbose the kdump process should be. Read kdump(5) for details. </para><screen><KDUMP_VERBOSE>3</KDUMP_VERBOSE></screen></entry> <entry>optional</entry> -- To unsubscribe, e-mail: yast-commit+unsubscribe@opensuse.org For additional commands, e-mail: yast-commit+help@opensuse.org