Merge lp:~louis/serverguide/remote-kdump-update into lp:serverguide/trunk

[Louis Bouchard]

Added configuration details for the remote kernel crash dump functionality now included in Xenial

[Doug Smythies (dsmythies)]

I get the following warnings while compiling the PDF:

[INFO] FOUserAgent - Rendered page #17.
[WARN] FOUserAgent - Glyph "┌" (0x250c, SF010000) not available in font "Courier".
[WARN] FOUserAgent - Glyph "─" (0x2500, SF100000) not available in font "Courier".
[WARN] FOUserAgent - Glyph "┤" (0x2524, SF090000) not available in font "Courier".
[WARN] FOUserAgent - Glyph "├" (0x251c, SF080000) not available in font "Courier".
[WARN] FOUserAgent - Glyph "┐" (0x2510, SF030000) not available in font "Courier".
[WARN] FOUserAgent - Glyph "│" (0x2502, SF110000) not available in font "Courier".
[WARN] FOUserAgent - Glyph "└" (0x2514, SF020000) not available in font "Courier".
[WARN] FOUserAgent - Glyph "┘" (0x2518, SF040000) not available in font "Courier".
[INFO] FOUserAgent - Rendered page #18.

And when I check for non-ascii characters in the master English source, I get a bunch of hits (including one that snuck in there with Serge's MP).

See also:
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository/Members-Serverguide#ASCII_Policy

review: Needs Fixing

[Simon Quigley (tsimonq2)]

Lines 16-26 of the diff are the culprit, and in the LXD guide, Stephane Graber's name is the culprit of that warning. It's a really simple fix, and I have a fix that you could do the following with:

============================================================

bzr merge lp:~tsimonq2/serverguide/fix-remote-kdump-update

bzr commit -m "Merged Simon's fix"

bzr push lp:~louis-bouchard/serverguide/remote-kdump-update

============================================================

Link to my fix: https://code.launchpad.net/~tsimonq2/serverguide/fix-remote-kdump-update

[Doug Smythies (dsmythies)]

Simon, thanks. Yes, I knew what the problem was, just didn't have time to fix it myself.

[Doug Smythies (dsmythies)]

O.K. I did the same edits as Simon proposed and will push this into trunk.

review: Approve

=== modified file 'serverguide/C/installation.xml'
--- serverguide/C/installation.xml	2016-04-07 00:08:38 +0000
+++ serverguide/C/installation.xml	2016-04-07 13:43:00 +0000
@@ -1402,21 +1402,131 @@
 <command>sudo apt install linux-crashdump</command>
 </screen>
 
-       </sect2>
+
+      <note>
+        <para>Starting with 16.04, the kernel crash dump mechanism is enabled by default. During the installation, you will be prompted with the following dialog. Unless chosen otherwise, the kdump mechanism will be enabled.
+        </para>
+      </note>
+
+      <screen>
+ ┌────────────────────────┤ Configuring kdump-tools ├────────────────────────┐
+ │                                                                           │
+ │ If you choose this option, the kdump-tools mechanism will be enabled. A   │
+ │ reboot is still required in order to enable the crashkernel kernel        │
+ │ parameter.                                                                │
+ │                                                                           │
+ │ Should kdump-tools be enabled by default?                                 │
+ │                                                                           │
+ │                    <emphasis role="bold">&lt;Yes&gt;</emphasis>                       &lt;No&gt;                       │
+ │                                                                           │
+ └───────────────────────────────────────────────────────────────────────────┘
+        </screen>
+        <para>
+          If you ever need to manually enable the functionality, you can use the <command>dpkg-reconfigure kdump-tools</command> command and answer Yes to the question. You can also edit <filename>/etc/default/kdump-tools</filename> by including the following line:
+<programlisting>
+USE_KDUMP=1
+</programlisting>
+      </para>
+
+      <para>
+      If a reboot has not been done since installation of the linux-crashdump package, a reboot will be required in order to activate the crashkernel= boot parameter. Upon reboot, kdump-tools will be enabled and active.
+      </para>
+      <para>
+        If you enable kdump-tools after a reboot, you will only need to issue the <command>kdump-config load</command> command to activate the kdump mechanism.
+      </para>
+      </sect2>
       <sect2 id="kernel-dump-configuration" status="review">
       <title>Configuration</title>
 
       <para>
-      Edit <filename>/etc/default/kdump-tools</filename> by including the following line:
-<programlisting>
-USE_KDUMP=1
-</programlisting>
+        In addition to local dump, it is now possible to use the remote dump functionality to send the kernel crash dump to a remote server, using either the <emphasis>SSH</emphasis> or <emphasis>NFS</emphasis> protocols.
       </para>
-
+      <sect3 id="local-dump" status="review">
+        <title>Local Kernel Crash Dumps</title>
+        <para>
+          Local dumps are configured automatically and will remain in use unless a remote protocol is chosen. Many configuration options exist and are thoroughly documented in the <filename>/etc/default/kdump-tools</filename> file.
+        </para>
+      </sect3>
+
+      <sect3 id="ssh-dump" status="review">
+        <title>Remote Kernel Crash Dumps using the SSH protocol</title>
+        <para>
+          To enable remote dumps using the <emphasis>SSH</emphasis> protocol, the <filename>/etc/default/kdump-tools</filename> must be modified in the following manner :</para>
+        <programlisting>
+# ---------------------------------------------------------------------------
+# Remote dump facilities:
+# SSH - username and hostname of the remote server that will receive the dump
+#       and dmesg files.
+# SSH_KEY - Full path of the ssh private key to be used to login to the remote
+#           server. use kdump-config propagate to send the public key to the
+#           remote server
+# HOSTTAG - Select if hostname of IP address will be used as a prefix to the
+#           timestamped directory when sending files to the remote server.
+#           'ip' is the default.
+<emphasis role="bold">SSH="ubuntu@kdump-netcrash"</emphasis>
+        </programlisting>
+        <para>The only mandatory variable to define is SSH. It must contain the username and hostname of the remote server using the format {username}@{remote server}.</para>
+
+        <para>SSH_KEY may be used to provide an existing private key to be used. Otherwise, the <command>kdump-config propagate</command> command will create a new keypair. The HOSTTAG variable may be used to use the hostname of the system as a prefix to the remote directory to be created instead of the IP address. </para>
+
+        <para>The following example shows how <command>kdump-config propagate</command> is used to create and propagate a new keypair to the remote server :
+        <screen>
+<command>sudo kdump-config propagate</command>
+Need to generate a new ssh key...
+The authenticity of host 'kdump-netcrash (192.168.1.74)' can't be established.
+ECDSA key fingerprint is SHA256:iMp+5Y28qhbd+tevFCWrEXykDd4dI3yN4OVlu3CBBQ4.
+Are you sure you want to continue connecting (yes/no)? yes
+ubuntu@kdump-netcrash's password: 
+propagated ssh key /root/.ssh/kdump_id_rsa to server ubuntu@kdump-netcrash
+        </screen>
+        The password of the account used on the remote server will be required in order to successfully send the public key to the server</para>
+        <para>
+        The <command>kdump-config show</command> command can be used to confirm that kdump is correctly configured to use the SSH protocol :
+        <screen>
+<command>kdump-config show</command>
+DUMP_MODE:        kdump
+USE_KDUMP:        1
+KDUMP_SYSCTL:     kernel.panic_on_oops=1
+KDUMP_COREDIR:    /var/crash
+crashkernel addr: 0x2c000000
+   /var/lib/kdump/vmlinuz: symbolic link to /boot/vmlinuz-4.4.0-10-generic
+kdump initrd: 
+   /var/lib/kdump/initrd.img: symbolic link to /var/lib/kdump/initrd.img-4.4.0-10-generic
+<emphasis role="bold">SSH:              ubuntu@kdump-netcrash
+SSH_KEY:          /root/.ssh/kdump_id_rsa
+HOSTTAG:          ip
+current state:    ready to kdump</emphasis>
+        </screen></para>
+      </sect3>
+
+      <sect3 id="nfs-dump" status="review">
+        <title>Remote Kernel Crash Dumps using the NFS protocol</title>
       <para>
-      A reboot is then needed.
-      </para>
-
+          To enable remote dumps using the <emphasis>NFS</emphasis> protocol, the <filename>/etc/default/kdump-tools</filename> must be modified in the following manner :</para>
+          <programlisting>
+# NFS -     Hostname and mount point of the NFS server configured to receive
+#           the crash dump. The syntax must be {HOSTNAME}:{MOUNTPOINT} 
+#           (e.g. remote:/var/crash)
+#
+<emphasis role="bold">NFS="kdump-netcrash:/var/crash"</emphasis>
+          </programlisting>
+          <para>As with the SSH protocol, the HOSTTAG variable can be used to replace the IP address by the hostname as the prefix of the remote directory.</para>
+          <para>The <command>kdump-config show</command> command can be used to confirm that kdump is correctly configured to use the NFS protocol :
+        <screen>
+<command>kdump-config show</command>
+DUMP_MODE:        kdump
+USE_KDUMP:        1
+KDUMP_SYSCTL:     kernel.panic_on_oops=1
+KDUMP_COREDIR:    /var/crash
+crashkernel addr: 0x2c000000
+   /var/lib/kdump/vmlinuz: symbolic link to /boot/vmlinuz-4.4.0-10-generic
+kdump initrd: 
+   /var/lib/kdump/initrd.img: symbolic link to /var/lib/kdump/initrd.img-4.4.0-10-generic
+<emphasis role="bold">NFS:              kdump-netcrash:/var/crash
+HOSTTAG:          hostname
+current state:    ready to kdump</emphasis>
+      </screen></para>
+        </sect3>
       </sect2>
 
       <sect2 id="verification" status="review">
@@ -1471,6 +1581,24 @@
 </computeroutput>
 </screen>
 
+      <para>
+      Finally, as seen previously, the <command>kdump-config show</command> command displays the current status of the kdump-tools configuration :
+      <screen>
+        <command>kdump-config show
+</command>DUMP_MODE:        kdump
+USE_KDUMP:        1
+KDUMP_SYSCTL:     kernel.panic_on_oops=1
+KDUMP_COREDIR:    /var/crash
+crashkernel addr: 0x2c000000
+   /var/lib/kdump/vmlinuz: symbolic link to /boot/vmlinuz-4.4.0-10-generic
+kdump initrd: 
+      /var/lib/kdump/initrd.img: symbolic link to /var/lib/kdump/initrd.img-4.4.0-10-generic
+current state:    ready to kdump
+
+kexec command:
+      /sbin/kexec -p --command-line="BOOT_IMAGE=/vmlinuz-4.4.0-10-generic root=/dev/mapper/VividS--vg-root ro debug break=init console=ttyS0,115200 irqpoll maxcpus=1 nousb systemd.unit=kdump-tools.service" --initrd=/var/lib/kdump/initrd.img /var/lib/kdump/vmlinuz
+      </screen>
+      </para>
       </sect2>
 
       <sect2 id="kdump-testing" status="review">