docs: improve compressed core file documentation

[vpp.git] / docs / troubleshooting / reportingissues / reportingissues.rst

diff --git a/docs/troubleshooting/reportingissues/reportingissues.rst b/docs/troubleshooting/reportingissues/reportingissues.rst
index 73b2397..9192e20 100644 (file)
--- a/docs/troubleshooting/reportingissues/reportingissues.rst
+++ b/docs/troubleshooting/reportingissues/reportingissues.rst
@@ -198,9 +198,16 @@ If you start VPP from systemd, you also need to edit
 /lib/systemd/system/vpp.service and uncomment the "LimitCORE=infinity"
 line before restarting VPP.
 
 /lib/systemd/system/vpp.service and uncomment the "LimitCORE=infinity"
 line before restarting VPP.
 

-Vpp core files often appear enormous. Gzip typically compresses them
-to manageable sizes. A multi-GByte corefile often compresses to 10-20
-Mbytes.
+Vpp core files often appear enormous, but they are invariably
+sparse. Gzip compresses them to manageable sizes. A multi-GByte
+corefile often compresses to 10-20 Mbytes.
+
+When decompressing a vpp core file, we suggest using "dd" as shown to
+create a sparse, uncompressed core file:
+
+.. code-block:: console
+
+   $ zcat vpp_core.gz | dd conv=sparse of=vpp_core

 
 Please remember to put compressed core files in accessible places.
 
 
 Please remember to put compressed core files in accessible places.
 


@@ -209,6 +216,9 @@ Make sure to leave the default stanza "... unix { ... full-coredump
 /etc/vpp/startup.conf, or to include it in the command line arguments
 passed by orchestration software.
 
 /etc/vpp/startup.conf, or to include it in the command line arguments
 passed by orchestration software.
 

+Core files from Private Images
+==============================
+

 Core files from private images require special handling. If it's
 necessary to go that route, copy the **exact** Debian packages (or
 RPMs) which correspond to the core file to the same public place as
 Core files from private images require special handling. If it's
 necessary to go that route, copy the **exact** Debian packages (or
 RPMs) which correspond to the core file to the same public place as


@@ -238,6 +248,33 @@ Even given a byte-for-byte identical source tree, it's easy to build
 dramatically different binary artifacts. All it takes is a different
 toolchain version.
 
 dramatically different binary artifacts. All it takes is a different
 toolchain version.
 

+
+On-the-fly Core File Compression
+--------------------------------
+
+Depending on operational requirements, it's possible to compress
+corefiles as they are generated. Please note that it takes several
+seconds' worth of wall-clock time to compress a vpp core file on the
+fly, during which all packet processing activities are suspended.
+
+To create compressed core files on the fly, create the following
+script, e.g. in /usr/local/bin/compressed_corefiles, owned by root,
+executable:
+
+.. code-block:: console
+
+  #!/bin/sh
+  exec /bin/gzip -f - >"/tmp/dumps/core-$1.$2.gz"
+
+Adjust the kernel core file pattern as shown:
+
+.. code-block:: console
+
+  sysctl -w kernel.core_pattern="|/usr/local/bin/compressed_corefiles %e %t"
+
+Core File Summary
+-----------------
+

 Bottom line: please follow core file handling instructions to the
 letter. It's not complicated. Simply copy the exact Debian packages or
 RPMs which correspond to core files to accessible locations.
 Bottom line: please follow core file handling instructions to the
 letter. It's not complicated. Simply copy the exact Debian packages or
 RPMs which correspond to core files to accessible locations.