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     </variablelist>
 260   </refsect1>
 261
 262   <refsect1>
 263     <title>Matching</title>
 264
 265     <para>A match can be:</para>
 266
 267     <variablelist>
 268       <varlistentry>
 269         <term><replaceable>PID</replaceable></term>
 270
 271         <listitem><para>Process ID of the
 272         process that dumped
 273         core. An integer.</para></listitem>
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term><replaceable>COMM</replaceable></term>
 278
 279         <listitem><para>Name of the executable (matches
 280         <option>COREDUMP_COMM=</option>). Must not contain slashes.
 281         </para></listitem>
 282       </varlistentry>
 283
 284       <varlistentry>
 285         <term><replaceable>EXE</replaceable></term>
 286
 287         <listitem><para>Path to the executable (matches
 288         <option>COREDUMP_EXE=</option>). Must contain at least one
 289         slash. </para></listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><replaceable>MATCH</replaceable></term>
 294
 295         <listitem><para>General journalctl match filter, must contain an equals
 296         sign (<literal>=</literal>). See
 297         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 298         </para></listitem>
 299       </varlistentry>
 300     </variablelist>
 301   </refsect1>
 302
 303   <refsect1>
 304     <title>Exit status</title>
 305     <para>On success, 0 is returned; otherwise, a non-zero failure
 306     code is returned. Not finding any matching core dumps is treated as
 307     failure.
 308     </para>
 309   </refsect1>
 310
 311   <refsect1>
 312     <title>Environment</title>
 313
 314     <variablelist class='environment-variables'>
 315       <varlistentry>
 316         <term><varname>$SYSTEMD_DEBUGGER</varname></term>
 317         <listitem><para>Use the given debugger for the <command>debug</command>
 318         command. See the <option>--debugger=</option> option.</para></listitem>
 319       </varlistentry>
 320     </variablelist>
 321   </refsect1>
 322
 323   <refsect1>
 324     <title>Examples</title>
 325
 326     <example>
 327       <title>List all the core dumps of a program</title>
 328
 329       <programlisting>$ coredumpctl list /usr/lib64/firefox/firefox
 330 TIME     PID  UID  GID SIG     COREFILE EXE                         SIZE
 331 Tue …   8018 1000 1000 SIGSEGV missing  /usr/lib64/firefox/firefox   n/a
 332 Wed … 251609 1000 1000 SIGTRAP missing  /usr/lib64/firefox/firefox   n/a
 333 Fri … 552351 1000 1000 SIGSEGV present  /usr/lib64/firefox/firefox 28.7M
 334 </programlisting>
 335
 336        <para>The journal has three entries pertaining to <filename>/usr/lib64/firefox/firefox</filename>, and
 337        only the last entry still has an available core file (in external storage on disk).</para>
 338
 339        <para>Note that <filename>coredumpctl</filename> needs access to the journal files to retrieve the
 340        relevant entries from the journal. Thus, an unprivileged user will normally only see information about
 341        crashing programs of this user.</para>
 342     </example>
 343
 344     <example>
 345       <title>Invoke <command>gdb</command> on the last core dump</title>
 346
 347       <programlisting>$ coredumpctl debug</programlisting>
 348     </example>
 349
 350     <example>
 351       <title>Use <command>gdb</command> to display full register info from the last core dump</title>
 352
 353       <programlisting>$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
 354     </example>
 355
 356     <example>
 357       <title>Show information about a core dump matched by PID</title>
 358
 359       <programlisting>$ coredumpctl info 6654
 360            PID: 6654 (bash)
 361            UID: 1000 (user)
 362            GID: 1000 (user)
 363         Signal: 11 (SEGV)
 364      Timestamp: Mon 2021-01-01 00:00:01 CET (20s ago)
 365   Command Line: bash -c $'kill -SEGV $$'
 366     Executable: /usr/bin/bash
 367  Control Group: /user.slice/user-1000.slice/…
 368           Unit: user@1000.service
 369      User Unit: vte-spawn-….scope
 370          Slice: user-1000.slice
 371      Owner UID: 1000 (user)
 372        Boot ID: …
 373     Machine ID: …
 374       Hostname: …
 375        Storage: /var/lib/systemd/coredump/core.bash.1000.….zst (present)
 376      Disk Size: 51.7K
 377        Message: Process 130414 (bash) of user 1000 dumped core.
 378
 379                 Stack trace of thread 130414:
 380                 #0  0x00007f398142358b kill (libc.so.6 + 0x3d58b)
 381                 #1  0x0000558c2c7fda09 kill_builtin (bash + 0xb1a09)
 382                 #2  0x0000558c2c79dc59 execute_builtin.lto_priv.0 (bash + 0x51c59)
 383                 #3  0x0000558c2c79709c execute_simple_command (bash + 0x4b09c)
 384                 #4  0x0000558c2c798408 execute_command_internal (bash + 0x4c408)
 385                 #5  0x0000558c2c7f6bdc parse_and_execute (bash + 0xaabdc)
 386                 #6  0x0000558c2c85415c run_one_command.isra.0 (bash + 0x10815c)
 387                 #7  0x0000558c2c77d040 main (bash + 0x31040)
 388                 #8  0x00007f398140db75 __libc_start_main (libc.so.6 + 0x27b75)
 389                 #9  0x0000558c2c77dd1e _start (bash + 0x31d1e)
 390 </programlisting>
 391     </example>
 392
 393     <example>
 394       <title>Extract the last core dump of /usr/bin/bar to a file named
 395       <filename index="false">bar.coredump</filename></title>
 396
 397       <programlisting>$ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
 398     </example>
 399   </refsect1>
 400
 401   <refsect1>
 402     <title>See Also</title>
 403     <para>
 404       <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 405       <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 406       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 407       <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 408     </para>
 409   </refsect1>
 410
 411 </refentry>