man/coredumpctl.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="coredumpctl" conditional='ENABLE_COREDUMP'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>coredumpctl</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>coredumpctl</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>coredumpctl</refname>
  21     <refpurpose>Retrieve and process saved core dumps and metadata</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>coredumpctl</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="req">COMMAND</arg>
  29       <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg>
  30     </cmdsynopsis>
  31   </refsynopsisdiv>
  32
  33   <refsect1>
  34     <title>Description</title>
  35
  36     <para><command>coredumpctl</command> is a tool that can be used to retrieve and process core
  37     dumps and metadata which were saved by
  38     <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  39     </para>
  40   </refsect1>
  41
  42   <refsect1>
  43     <title>Commands</title>
  44
  45     <para>The following commands are understood:</para>
  46
  47     <variablelist>
  48       <varlistentry>
  49         <term><command>list</command></term>
  50
  51         <listitem><para>List core dumps captured in the journal
  52         matching specified characteristics. If no command is
  53         specified, this is the implied default.</para>
  54
  55         <para>The output is designed to be human readable and contains a table with the following
  56         columns:</para>
  57         <variablelist>
  58           <varlistentry>
  59             <term>TIME</term>
  60             <listitem><para>The timestamp of the crash, as reported by the kernel.</para>
  61             </listitem>
  62           </varlistentry>
  63
  64           <varlistentry>
  65             <term>PID</term>
  66             <listitem><para>The identifier of the process that crashed.</para>
  67             </listitem>
  68           </varlistentry>
  69
  70           <varlistentry>
  71             <term>UID</term>
  72             <term>GID</term>
  73             <listitem><para>The user and group identifiers of the process that crashed.</para>
  74             </listitem>
  75           </varlistentry>
  76
  77           <varlistentry>
  78             <term>SIGNAL</term>
  79             <listitem><para>The signal that caused the process to crash, when applicable.
  80             </para></listitem>
  81           </varlistentry>
  82
  83           <varlistentry>
  84             <term>COREFILE</term>
  85             <listitem><para>Information whether the coredump was stored, and whether
  86             it is still accessible: <literal>none</literal> means the core was
  87             not stored, <literal>-</literal> means that it was not available (for
  88             example because the process was not terminated by a signal),
  89             <literal>present</literal> means that the core file is accessible by the
  90             current user, <literal>journal</literal> means that the core was stored
  91             in the <literal>journal</literal>, <literal>truncated</literal> is the
  92             same as one of the previous two, but the core was too large and was not
  93             stored in its entirety, <literal>error</literal> means that the core file
  94             cannot be accessed, most likely because of insufficient permissions, and
  95             <literal>missing</literal> means that the core was stored in a file, but
  96             this file has since been removed.</para></listitem>
  97           </varlistentry>
  98
  99           <varlistentry>
 100             <term>EXE</term>
 101             <listitem><para>The full path to the executable. For backtraces of scripts
 102             this is the name of the interpreter.</para></listitem>
 103           </varlistentry>
 104         </variablelist>
 105
 106         <para>It's worth noting that different restrictions apply to
 107         data saved in the journal and core dump files saved in
 108         <filename>/var/lib/systemd/coredump</filename>, see overview in
 109         <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 110         Thus it may very well happen that a particular core dump is still listed
 111         in the journal while its corresponding core dump file has already been
 112         removed.</para></listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><command>info</command></term>
 117
 118         <listitem><para>Show detailed information about the last core dump
 119         or core dumps matching specified characteristics
 120         captured in the journal.</para></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><command>dump</command></term>
 125
 126         <listitem><para>Extract the last core dump matching specified
 127         characteristics. The core dump will be written on standard
 128         output, unless an output file is specified with
 129         <option>--output=</option>. </para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><command>debug</command></term>
 134
 135         <listitem><para>Invoke a debugger on the last core dump
 136         matching specified characteristics. By default,
 137         <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 138         will be used. This may be changed using the <option>--debugger=</option>
 139         option or the <varname>$SYSTEMD_DEBUGGER</varname> environment
 140         variable. Use the <option>--debugger-arguments=</option> option to pass extra
 141         command line arguments to the debugger.</para></listitem>
 142       </varlistentry>
 143
 144     </variablelist>
 145
 146   </refsect1>
 147
 148   <refsect1>
 149     <title>Options</title>
 150
 151     <para>The following options are understood:</para>
 152
 153     <variablelist>
 154
 155       <xi:include href="standard-options.xml" xpointer="help" />
 156       <xi:include href="standard-options.xml" xpointer="version" />
 157       <xi:include href="standard-options.xml" xpointer="no-pager" />
 158       <xi:include href="standard-options.xml" xpointer="no-legend" />
 159       <xi:include href="standard-options.xml" xpointer="json" />
 160
 161       <varlistentry>
 162         <term><option>-1</option></term>
 163
 164         <listitem><para>Show information of the most recent core dump only, instead of listing all known core
 165         dumps. Equivalent to <option>--reverse -n 1</option>.</para></listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><option>-n</option> <replaceable>INT</replaceable></term>
 170
 171         <listitem><para>Show at most the specified number of entries. The specified parameter must be an
 172         integer greater or equal to 1.</para></listitem>
 173       </varlistentry>
 174
 175       <varlistentry>
 176         <term><option>-S</option></term>
 177         <term><option>--since</option></term>
 178
 179         <listitem><para>Only print entries which are since the specified date.</para></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><option>-U</option></term>
 184         <term><option>--until</option></term>
 185
 186         <listitem><para>Only print entries which are until the specified date.</para></listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><option>-r</option></term>
 191         <term><option>--reverse</option></term>
 192
 193         <listitem><para>Reverse output so that the newest entries are displayed first.
 194         </para></listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term><option>-F</option> <replaceable>FIELD</replaceable></term>
 199         <term><option>--field=</option><replaceable>FIELD</replaceable></term>
 200
 201         <listitem><para>Print all possible data values the specified
 202         field takes in matching core dump entries of the
 203         journal.</para></listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term><option>-o</option> <replaceable>FILE</replaceable></term>
 208         <term><option>--output=</option><replaceable>FILE</replaceable></term>
 209
 210         <listitem><para>Write the core to <option>FILE</option>.
 211         </para></listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><option>--debugger=</option><replaceable>DEBUGGER</replaceable></term>
 216
 217         <listitem><para>Use the given debugger for the <command>debug</command>
 218         command. If not given and <varname>$SYSTEMD_DEBUGGER</varname> is unset, then
 219         <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 220         will be used. </para></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term><option>-A</option> <replaceable>ARGS</replaceable></term>
 225         <term><option>--debugger-arguments=</option><replaceable>ARGS</replaceable></term>
 226
 227         <listitem><para>Pass the given <replaceable>ARGS</replaceable> as extra command line arguments
 228         to the debugger. Quote as appropriate when <replaceable>ARGS</replaceable> contain whitespace.
 229         (See Examples.)</para></listitem>
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term><option>--file=<replaceable>GLOB</replaceable></option></term>
 234
 235         <listitem><para>Takes a file glob as an argument. If
 236         specified, coredumpctl will operate on the specified journal
 237         files matching <replaceable>GLOB</replaceable> instead of the
 238         default runtime and system journal paths. May be specified
 239         multiple times, in which case files will be suitably
 240         interleaved.</para></listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><option>-D</option> <replaceable>DIR</replaceable></term>
 245         <term><option>--directory=</option><replaceable>DIR</replaceable></term>
 246
 247         <listitem><para>Use the journal files in the specified <option>DIR</option>.
 248         </para></listitem>
 249       </varlistentry>
 250
 251       <varlistentry>
 252         <term><option>-q</option></term>
 253         <term><option>--quiet</option></term>
 254
 255         <listitem><para>Suppresses informational messages about lack
 256         of access to journal files and possible in-flight coredumps.
 257         </para></listitem>
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term><option>--all</option></term>
 262
 263         <listitem><para>Look at all available journal files in <filename>/var/log/journal/</filename>
 264         (excluding journal namespaces) instead of only local ones.</para></listitem>
 265       </varlistentry>
 266     </variablelist>
 267   </refsect1>
 268
 269   <refsect1>
 270     <title>Matching</title>
 271
 272     <para>A match can be:</para>
 273
 274     <variablelist>
 275       <varlistentry>
 276         <term><replaceable>PID</replaceable></term>
 277
 278         <listitem><para>Process ID of the
 279         process that dumped
 280         core. An integer.</para></listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term><replaceable>COMM</replaceable></term>
 285
 286         <listitem><para>Name of the executable (matches
 287         <option>COREDUMP_COMM=</option>). Must not contain slashes.
 288         </para></listitem>
 289       </varlistentry>
 290
 291       <varlistentry>
 292         <term><replaceable>EXE</replaceable></term>
 293
 294         <listitem><para>Path to the executable (matches
 295         <option>COREDUMP_EXE=</option>). Must contain at least one
 296         slash. </para></listitem>
 297       </varlistentry>
 298
 299       <varlistentry>
 300         <term><replaceable>MATCH</replaceable></term>
 301
 302         <listitem><para>General journalctl match filter, must contain an equals
 303         sign (<literal>=</literal>). See
 304         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 305         </para></listitem>
 306       </varlistentry>
 307     </variablelist>
 308   </refsect1>
 309
 310   <refsect1>
 311     <title>Exit status</title>
 312     <para>On success, 0 is returned; otherwise, a non-zero failure
 313     code is returned. Not finding any matching core dumps is treated as
 314     failure.
 315     </para>
 316   </refsect1>
 317
 318   <refsect1>
 319     <title>Environment</title>
 320
 321     <variablelist class='environment-variables'>
 322       <varlistentry>
 323         <term><varname>$SYSTEMD_DEBUGGER</varname></term>
 324         <listitem><para>Use the given debugger for the <command>debug</command>
 325         command. See the <option>--debugger=</option> option.</para></listitem>
 326       </varlistentry>
 327     </variablelist>
 328   </refsect1>
 329
 330   <refsect1>
 331     <title>Examples</title>
 332
 333     <example>
 334       <title>List all the core dumps of a program</title>
 335
 336       <programlisting>$ coredumpctl list /usr/lib64/firefox/firefox
 337 TIME       PID  UID  GID SIG     COREFILE EXE                         SIZE
 338 Tue …   8018 1000 1000 SIGSEGV missing  /usr/lib64/firefox/firefox     -
 339 Wed … 251609 1000 1000 SIGTRAP missing  /usr/lib64/firefox/firefox     -
 340 Fri … 552351 1000 1000 SIGSEGV present  /usr/lib64/firefox/firefox 28.7M
 341 </programlisting>
 342
 343        <para>The journal has three entries pertaining to <filename>/usr/lib64/firefox/firefox</filename>, and
 344        only the last entry still has an available core file (in external storage on disk).</para>
 345
 346        <para>Note that <filename>coredumpctl</filename> needs access to the journal files to retrieve the
 347        relevant entries from the journal. Thus, an unprivileged user will normally only see information about
 348        crashing programs of this user.</para>
 349     </example>
 350
 351     <example>
 352       <title>Invoke <command>gdb</command> on the last core dump</title>
 353
 354       <programlisting>$ coredumpctl debug</programlisting>
 355     </example>
 356
 357     <example>
 358       <title>Use <command>gdb</command> to display full register info from the last core dump</title>
 359
 360       <programlisting>$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
 361     </example>
 362
 363     <example>
 364       <title>Show information about a core dump matched by PID</title>
 365
 366       <programlisting>$ coredumpctl info 6654
 367            PID: 6654 (bash)
 368            UID: 1000 (user)
 369            GID: 1000 (user)
 370         Signal: 11 (SEGV)
 371      Timestamp: Mon 2021-01-01 00:00:01 CET (20s ago)
 372   Command Line: bash -c $'kill -SEGV $$'
 373     Executable: /usr/bin/bash
 374  Control Group: /user.slice/user-1000.slice/…
 375           Unit: user@1000.service
 376      User Unit: vte-spawn-….scope
 377          Slice: user-1000.slice
 378      Owner UID: 1000 (user)
 379        Boot ID: …
 380     Machine ID: …
 381       Hostname: …
 382        Storage: /var/lib/systemd/coredump/core.bash.1000.….zst (present)
 383   Size on Disk: 51.7K
 384        Message: Process 130414 (bash) of user 1000 dumped core.
 385
 386                 Stack trace of thread 130414:
 387                 #0  0x00007f398142358b kill (libc.so.6 + 0x3d58b)
 388                 #1  0x0000558c2c7fda09 kill_builtin (bash + 0xb1a09)
 389                 #2  0x0000558c2c79dc59 execute_builtin.lto_priv.0 (bash + 0x51c59)
 390                 #3  0x0000558c2c79709c execute_simple_command (bash + 0x4b09c)
 391                 #4  0x0000558c2c798408 execute_command_internal (bash + 0x4c408)
 392                 #5  0x0000558c2c7f6bdc parse_and_execute (bash + 0xaabdc)
 393                 #6  0x0000558c2c85415c run_one_command.isra.0 (bash + 0x10815c)
 394                 #7  0x0000558c2c77d040 main (bash + 0x31040)
 395                 #8  0x00007f398140db75 __libc_start_main (libc.so.6 + 0x27b75)
 396                 #9  0x0000558c2c77dd1e _start (bash + 0x31d1e)
 397 </programlisting>
 398     </example>
 399
 400     <example>
 401       <title>Extract the last core dump of /usr/bin/bar to a file named
 402       <filename index="false">bar.coredump</filename></title>
 403
 404       <programlisting>$ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
 405     </example>
 406   </refsect1>
 407
 408   <refsect1>
 409     <title>See Also</title>
 410     <para>
 411       <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 412       <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 413       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 414       <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 415     </para>
 416   </refsect1>
 417
 418 </refentry>