DOCTEAM 1865 systemd-coredump

DC-SLES-systemd-coredump

@@ -0,0 +1,17 @@
+## ----------------------------
+## Doc Config File for the DB Assembly test
+## ----------------------------
+##
+## Basics
+MAIN="SLES-systemd-coredump.asm.xml"
+SRC_DIR="articles"
+IMG_SRC_DIR="images"
+## Profiling
+PROFOS="sles"
+PROFCONDITION="16.0"
+
+## stylesheet location
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2021-ns"
+
+DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"

articles/SLES-systemd-coredump.asm.xml

@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<?xml-model href="https://cdn.docbook.org/schema/5.2/rng/assemblyxi.rnc"
+            type="application/relax-ng-compact-syntax"?>
+<!DOCTYPE assembly
+[
+    <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<assembly version="5.2" xml:lang="en"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:trans="http://docbook.org/ns/transclusion"
+          xmlns:its="http://www.w3.org/2005/11/its"
+          xmlns="http://docbook.org/ns/docbook">
+  <!-- R E S O U R C E S -->
+
+  <!-- Concept files -->
+  <resources>
+    <resource xml:id="_systemd-coredump-usage" href="../concepts/systemd-coredump-usage.xml">
+      <description>About systemd</description>
+    </resource>
+    </resources>
+  <!-- Tasks-->
+  <resources>
+    <resource xml:id="_systemd-coredump-create-analyze" href="../tasks/systemd-coredump-create-analyze.xml">
+      <description>systemd-coredump creating and analyzing</description>
+    </resource>
+  </resources>
+  <!--References-->
+  <resources>
+    <resource xml:id="_systemd-coredump-configuration" href="../references/systemd-coredump-configuration.xml">
+      <description>systemd-coredump Configuration</description>
+    </resource>
+  </resources>
+  <!-- Miscellaneous -->
+  <resources>
+    <resource href="../common/legal.xml" xml:id="_legal">
+      <description>Legal Notice</description>
+    </resource>
+    <resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
+      <description>GNU Free Documentation License</description>
+    </resource>
+  </resources>
+  <!-- S T R U C T U R E -->
+  <structure renderas="article" xml:id="systemd-services" xml:lang="en">
+    <merge>
+      <title>Managing Core Dumps with <command>systemd-coredump</command></title>
+      <revhistory xml:id="rh-systemd-services">
+        <revision><date>2026-03-27</date>
+          <revdescription>
+            <para>
+              Initial version
+            </para>
+          </revdescription>
+        </revision>
+      </revhistory>
+
+      <!-- Maintainer-->
+      <meta name="maintainer" content="shalaka.harne@suse.com" its:translate="no"/>
+
+      <!-- Series-->
+      <meta name="series" its:translate="no">Products &amp; Solutions</meta>
+
+      <!-- Task -->
+      <meta name="task" its:translate="no">
+        <phrase>Administration</phrase>
+        <phrase>Configuration</phrase>
+      </meta>
+
+      <!-- Docmanager -->
+      <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
+        <dm:bugtracker>
+          <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
+          <dm:component>Documentation</dm:component>
+          <dm:product os="sles;sles4sap">SUSE Linux Enterprise Server 16.0</dm:product>
+          <dm:product os="slmicro">SUSE Linux Micro 6.2</dm:product>
+          <dm:assignee>amrita.sakthivel@suse.com</dm:assignee>
+        </dm:bugtracker>
+        <dm:translation>yes</dm:translation>
+      </dm:docmanager>
+
+      <!-- Architecture -->
+      <meta name="architecture" its:translate="no">
+        <phrase>&x86-64;</phrase>
+        <phrase>&power;</phrase>
+        <phrase>&zseries;</phrase>
+        <phrase>&aarch64;</phrase>
+      </meta>
+
+      <!-- Productname & Version -->
+      <meta name="productname" its:translate="no">
+        <productname os="sles;sles4sap" version="16.0">&productname;</productname>
+        <productname version="6.2" os="slmicro">&productname;</productname>
+      </meta>
+
+      <!-- Social Media -->
+      <meta name="title" its:translate="yes">Managing Core Dumps with systemd-coredump</meta>
+      <meta name="social-descr" its:translate="yes">Configure systemd-coredump and analyze crash data</meta>
+
+      <!-- Search -->
+      <meta name="description" its:translate="yes">Learn how to configure systemd-coredump, collect and analyze core dumps, and manage crash data and storage</meta>
+
+      <abstract>
+        <variablelist>
+          <varlistentry>
+            <term>WHAT?</term>
+            <listitem>
+              <para>
+                From collecting and displaying core dumps, over providing stack traces for quick analysis to managing storage and retention, systemd-coredump enables you to investigate application crashes in a convenient way.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>WHY?</term>
+            <listitem>
+              <para>
+                This article provides a complete overview of the tasks that can be performed with systemd-coredump, such as collecting and displaying core dumps, providing backtraces for quick analysis, and managing the storage of crash data.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>EFFORT</term>
+            <listitem>
+              <para>
+               The average reading time of this article is approximately 40 minutes.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+<term>GOAL</term>
+<listitem>
+<para>
+You will be able to analyze and manage application crashes using systemd-coredump.
+</para>
+</listitem>
+</varlistentry>
+            <varlistentry>
+            <term>REQUIREMENTS</term>
+              <listitem>
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      Basic understanding of Linux commands
+                    </para>
+                  </listitem>
+                  <listitem>
+                  <para>
+                   Basic understanding of Linux processes
+                  </para>
+                  </listitem>
+                    </itemizedlist>
+              </listitem>
+            </varlistentry>
+        </variablelist>
+      </abstract>
+    </merge>
+    <!-- pull in all the topic files you need -->
+    <!-- pick the appropriate type of include to match your needs -->
+    <!-- pull in a topic as is -->
+    <!-- pull in a topic and switch the title -->
+    <module resourceref="_systemd-coredump-usage" renderas="section"/>
+    <module resourceref="_systemd-coredump-configuration" renderas="section"/>
+    <module resourceref="_systemd-coredump-create-analyze" renderas="section"/>
+    <module resourceref="_legal" renderas="section"/>
+    <module resourceref="_gfdl" renderas="appendix"/>
+
+    <!-- Troubleshooting -->
+  </structure>
+</assembly>

concepts/systemd-coredump-usage.xml

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
+<!-- This file can be edited downstream. -->
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+ <topic xml:id="systemd-coredump"
+       role="concept" xml:lang="en"
+       xmlns="http://docbook.org/ns/docbook" version="5.2"
+       xmlns:its="http://www.w3.org/2005/11/its"
+       xmlns:xi="http://www.w3.org/2001/XInclude"
+       xmlns:xlink="http://www.w3.org/1999/xlink"
+       xmlns:trans="http://docbook.org/ns/transclusion">
+       <info>
+        <title>Using <literal>systemd-coredump</literal> to debug application crashes</title>
+        <!--add author's email address-->
+        <meta name="maintainer" content="shalaka.harne@suse.com " its:translate="no"/>
+        <abstract>
+            <para>
+            systemd-coredump collects and displays core dumps to analyze application crashes. A core dump is an image of the process memory at the time of termination.
+            </para>
+            </abstract>
+        </info>
+        <section>
+<title>Using <literal>systemd-coredump</literal></title>
+<para>By default, when a process crashes, <literal>systemd-coredump</literal> performs the following actions:</para>
+<itemizedlist>
+    <listitem><para>Stores the core dump in <filename>/var/lib/systemd/coredump/</filename>.</para></listitem>
+    <listitem><para>Logs the event to the systemd journal.</para></listitem>
+    <listitem><para>Includes a backtrace where possible.</para></listitem>
+</itemizedlist>
+<para>You can examine the dump file using <command>coredumpctl</command> or external tools such as <command>gdb</command> or <command>crash</command>. </para>
+<note>
+<para>Core dumps stored in <filename>/var/lib/systemd/coredump/</filename> are by default automatically deleted after three days. This is configured through the <literal>d /var/lib/systemd/coredump</literal> 
+ line in <filename>/usr/lib/tmpfiles.d/systemd.conf</filename>. </para>
+
+<para>It is recommended not to edit <filename>/usr/lib/tmpfiles.d/systemd.conf</filename> directly, as the changes will be overwritten during the next system update. Hence, perform the following:</para>
+<procedure>
+    <step><para>Copy the file to <filename>/etc/tmpfiles.d/systemd.conf</filename>. As files in <filename>/etc/</filename> take precedence over those in <filename>/usr/lib/</filename>, your custom configuration is applied.</para></step>
+    <step><para>Open the file and find the line: <literal>d /var/lib/systemd/coredump</literal></para></step>
+    <step><para>Edit the age parameter; for example, change <literal>3d</literal> to <literal>7d</literal> to retain data for a week, or use the <literal>W</literal> notation for longer periods.</para></step>
+</procedure>
+</note>
+</section>
+</topic>

references/systemd-coredump-configuration.xml

@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<topic xml:id="systemd-coredump-configuration"
+ role="reference" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Configuration of <literal>systemd-coredump</literal></title>
+    <meta name="maintainer" content="shalaka.harne@suse.com" its:translate="no"/>
+    <abstract>
+      <para><literal>systemd-coredump</literal> provides a centralized, automated framework for capturing and managing process crashes by intercepting kernel signals to store compressed memory images and metadata, which are then easily analyzed through the <literal>coredumpctl</literal> utility.</para>
+    </abstract>
+  </info>
+  <para><literal>systemd-coredump</literal> is enabled by default. The primary configuration file is located at <filename>/etc/systemd/coredump.conf</filename>.</para>
+<screen>[Coredump]
+#Storage=external
+#Compress=yes
+#ProcessSizeMax=2G
+#ExternalSizeMax=2G
+#JournalSizeMax=767M
+#MaxUse=
+#KeepFree=</screen>
+<para>The following parameters in <filename>[Coredump]</filename> define how dumps are handled:</para>
+<variablelist><varlistentry>
+  <term><literal>Storage</literal></term>
+  <listitem><para>Defines where to store dumps such as <literal>none</literal>, <literal>external</literal>, <literal>journal</literal>. The default is <literal>external</literal>.</para>
+  <para>For example:</para>
+  <screen>[Coredump]
+# Directs dumps to be stored inside the system journal
+Storage=journal
+
+# Compress the data to save space within the journal
+Compress=yes
+
+# Limits the size of a single core dump stored in the journal to 500MB
+# If a process dump is larger than 500M, it will be dropped/ignored
+JournalSizeMax=500M
+
+# Processes larger than 1GB will not be handled at all
+ProcessSizeMax=1G</screen>
+  </listitem>
+</varlistentry>
+<varlistentry><term><literal>Compress</literal></term>
+  <listitem><para>Enables/disables compression for the stored core dump. By default, this is enabled.</para></listitem>
+</varlistentry>
+<varlistentry><term><literal>ProcessSizeMax</literal></term>
+<listitem><para>The maximum size of a core dump to be processed. The default size is <literal>2G</literal>.</para></listitem></varlistentry>
+<varlistentry><term><literal>ExternalSizeMax</literal></term>
+  <listitem><para>The maximum size for a dump stored on disk. The default size is <literal>2G</literal>, and this also supports a value of infinity.</para></listitem></varlistentry>
+<varlistentry>
+  <term><literal>JournalSizeMax</literal></term>
+    <listitem><para>The maximum size of core dumps that can be stored directly within the system journal (when Storage=journal is used). If a core dump exceeds this value, it will be ignored or handled according to other storage settings.</para></listitem></varlistentry>
+<varlistentry>
+  <term><literal>MaxUse</literal></term>
+  <listitem><para>The maximum amount of disk space the core dump storage (typically <filename>/var/lib/systemd/coredump/</filename>) is allowed to occupy. This value supports absolute sizes in bytes (e.g., <literal>2G</literal>) or a percentage of the total filesystem size (e.g., <literal>10%</literal>). Once this limit is reached, older core dumps are automatically deleted to make room for new ones.</para>
+  <para>The size units are <literal>B</literal>, <literal>K</literal>, <literal>M</literal>, <literal>G</literal>, <literal>T</literal>, <literal>P</literal>, and <literal>E</literal>.</para>
+  </listitem></varlistentry>
+<varlistentry>
+  <term><literal>KeepFree</literal></term>
+  <listitem><para>The minimum amount of free disk space to maintain on the filesystem where core dumps are stored. This value can be specified in bytes (using suffixes such as K, M, G) or as a percentage of the total filesystem size (e.g., <literal>15%</literal>). <literal>systemd-coredump</literal> will stop saving new dumps if the available disk space would fall below this threshold.</para>
+  <para>The size units are <literal>B</literal>, <literal>K</literal>, <literal>M</literal>, <literal>G</literal>, <literal>T</literal>, <literal>P</literal>, and <literal>E</literal>.</para>
+  </listitem></varlistentry>
+</variablelist>
+
+<note><para>A new instance of <literal>systemd-coredump</literal> is invoked for every crash. Configuration changes are applied immediately to the next crash; you do not need to restart any services.</para></note>
+<section><title>Managing core dump storage</title>
+    <para>To minimize the storage of sensitive information or prevent disk exhaustion in <filename>/var/lib/systemd/coredump</filename>, you can modify the <filename>Storage=</filename> option in <filename>/etc/systemd/coredump.conf</filename>.</para>
+<note><para>If the <filename>Storage=</filename> field is omitted, set to an empty value, or set to an invalid string, systemd defaults to <literal>external</literal>.</para></note>
+<para>The available storage options are:</para>
+    <itemizedlist>
+      <listitem><para><literal>Storage=none</literal> the event is logged to the journal, but the memory image (the core dump itself) is discarded and files are not created in <filename>/var/lib/systemd/coredump</filename>.</para></listitem>
+      <listitem><para><literal>Storage=journal</literal> The core dump is compressed and stored directly within the systemd journal metadata and files are not created in <filename>/var/lib/systemd/coredump</filename>. The storage is managed by <filename>/etc/systemd/journald.conf</filename> limits.</para></listitem>
+      <listitem><para><literal>Storage=external</literal> The event is logged to the journal, and the memory image is saved as a separate file. The files are created in <filename>/var/lib/systemd/coredump</filename>.</para></listitem>  
+    </itemizedlist>
+<para>As core dumps may not be preserved after a system restart (for example, if stored in volatile journal memory or a temporary directory), run the command below to save a core dump to a permanent file for later analysis:</para>
+<screen>coredumpctl -o my_app.dump dump &gt;PID&lt;</screen>
+<para>For more information, see <code>man systemd-coredump, man coredumpctl, man core, and man coredump.conf</code> for complete command and option listing.</para>
+</section>
+</topic>