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