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.5/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
  62             <xi:include href="version-info.xml" xpointer="v233"/>
  63             </listitem>
  64           </varlistentry>
  65
  66           <varlistentry>
  67             <term>PID</term>
  68             <listitem><para>The identifier of the process that crashed.</para>
  69
  70             <xi:include href="version-info.xml" xpointer="v233"/>
  71             </listitem>
  72           </varlistentry>
  73
  74           <varlistentry>
  75             <term>UID</term>
  76             <term>GID</term>
  77             <listitem><para>The user and group identifiers of the process that crashed.</para>
  78
  79             <xi:include href="version-info.xml" xpointer="v233"/>
  80             </listitem>
  81           </varlistentry>
  82
  83           <varlistentry>
  84             <term>SIGNAL</term>
  85             <listitem><para>The signal that caused the process to crash, when applicable.
  86             </para>
  87
  88             <xi:include href="version-info.xml" xpointer="v233"/></listitem>
  89           </varlistentry>
  90
  91           <varlistentry>
  92             <term>COREFILE</term>
  93             <listitem><para>Information whether the coredump was stored, and whether
  94             it is still accessible: <literal>none</literal> means the core was
  95             not stored, <literal>-</literal> means that it was not available (for
  96             example because the process was not terminated by a signal),
  97             <literal>present</literal> means that the core file is accessible by the
  98             current user, <literal>journal</literal> means that the core was stored
  99             in the <literal>journal</literal>, <literal>truncated</literal> is the
 100             same as one of the previous two, but the core was too large and was not
 101             stored in its entirety, <literal>error</literal> means that the core file
 102             cannot be accessed, most likely because of insufficient permissions, and
 103             <literal>missing</literal> means that the core was stored in a file, but
 104             this file has since been removed.</para>
 105
 106             <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 107           </varlistentry>
 108
 109           <varlistentry>
 110             <term>EXE</term>
 111             <listitem><para>The full path to the executable. For backtraces of scripts
 112             this is the name of the interpreter.</para>
 113
 114             <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 115           </varlistentry>
 116         </variablelist>
 117
 118         <para>It's worth noting that different restrictions apply to
 119         data saved in the journal and core dump files saved in
 120         <filename>/var/lib/systemd/coredump</filename>, see overview in
 121         <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 122         Thus it may very well happen that a particular core dump is still listed
 123         in the journal while its corresponding core dump file has already been
 124         removed.</para>
 125
 126         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><command>info</command></term>
 131
 132         <listitem><para>Show detailed information about the last core dump
 133         or core dumps matching specified characteristics
 134         captured in the journal.</para>
 135
 136         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><command>dump</command></term>
 141
 142         <listitem><para>Extract the last core dump matching specified
 143         characteristics. The core dump will be written on standard
 144         output, unless an output file is specified with
 145         <option>--output=</option>. </para>
 146
 147         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><command>debug</command></term>
 152
 153         <listitem><para>Invoke a debugger on the last core dump
 154         matching specified characteristics. By default,
 155         <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 156         will be used. This may be changed using the <option>--debugger=</option>
 157         option or the <varname>$SYSTEMD_DEBUGGER</varname> environment
 158         variable. Use the <option>--debugger-arguments=</option> option to pass extra
 159         command line arguments to the debugger.</para>
 160
 161         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 162       </varlistentry>
 163
 164     </variablelist>
 165
 166   </refsect1>
 167
 168   <refsect1>
 169     <title>Options</title>
 170
 171     <para>The following options are understood:</para>
 172
 173     <variablelist>
 174
 175       <xi:include href="standard-options.xml" xpointer="help" />
 176       <xi:include href="standard-options.xml" xpointer="version" />
 177       <xi:include href="standard-options.xml" xpointer="no-pager" />
 178       <xi:include href="standard-options.xml" xpointer="no-legend" />
 179       <xi:include href="standard-options.xml" xpointer="json" />
 180
 181       <varlistentry>
 182         <term><option>-1</option></term>
 183
 184         <listitem><para>Show information of the most recent core dump only, instead of listing all known core
 185         dumps. Equivalent to <option>--reverse -n 1</option>.</para>
 186
 187         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><option>-n</option> <replaceable>INT</replaceable></term>
 192
 193         <listitem><para>Show at most the specified number of entries. The specified parameter must be an
 194         integer greater or equal to 1.</para>
 195
 196         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 197       </varlistentry>
 198
 199       <varlistentry>
 200         <term><option>-S</option></term>
 201         <term><option>--since</option></term>
 202
 203         <listitem><para>Only print entries which are since the specified date.</para>
 204
 205         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term><option>-U</option></term>
 210         <term><option>--until</option></term>
 211
 212         <listitem><para>Only print entries which are until the specified date.</para>
 213
 214         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><option>-r</option></term>
 219         <term><option>--reverse</option></term>
 220
 221         <listitem><para>Reverse output so that the newest entries are displayed first.
 222         </para>
 223
 224         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 225       </varlistentry>
 226
 227       <varlistentry>
 228         <term><option>-F</option> <replaceable>FIELD</replaceable></term>
 229         <term><option>--field=<replaceable>FIELD</replaceable></option></term>
 230
 231         <listitem><para>Print all possible data values the specified
 232         field takes in matching core dump entries of the
 233         journal.</para>
 234
 235         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 236       </varlistentry>
 237
 238       <varlistentry>
 239         <term><option>-o</option> <replaceable>FILE</replaceable></term>
 240         <term><option>--output=<replaceable>FILE</replaceable></option></term>
 241
 242         <listitem><para>Write the core to <option>FILE</option>.
 243         </para>
 244
 245         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><option>--debugger=<replaceable>DEBUGGER</replaceable></option></term>
 250
 251         <listitem><para>Use the given debugger for the <command>debug</command>
 252         command. If not given and <varname>$SYSTEMD_DEBUGGER</varname> is unset, then
 253         <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 254         will be used. </para>
 255
 256         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 257       </varlistentry>
 258
 259       <varlistentry>
 260         <term><option>-A</option> <replaceable>ARGS</replaceable></term>
 261         <term><option>--debugger-arguments=<replaceable>ARGS</replaceable></option></term>
 262
 263         <listitem><para>Pass the given <replaceable>ARGS</replaceable> as extra command line arguments
 264         to the debugger. Quote as appropriate when <replaceable>ARGS</replaceable> contain whitespace.
 265         (See Examples.)</para>
 266
 267         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 268       </varlistentry>
 269
 270       <varlistentry>
 271         <term><option>--file=<replaceable>GLOB</replaceable></option></term>
 272
 273         <listitem><para>Takes a file glob as an argument. If
 274         specified, coredumpctl will operate on the specified journal
 275         files matching <replaceable>GLOB</replaceable> instead of the
 276         default runtime and system journal paths. May be specified
 277         multiple times, in which case files will be suitably
 278         interleaved.</para>
 279
 280         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term><option>-D</option> <replaceable>DIR</replaceable></term>
 285         <term><option>--directory=<replaceable>DIR</replaceable></option></term>
 286
 287         <listitem><para>Use the journal files in the specified <option>DIR</option>.
 288         </para>
 289
 290         <xi:include href="version-info.xml" xpointer="v225"/></listitem>
 291       </varlistentry>
 292
 293       <varlistentry>
 294         <term><option>--root=<replaceable>ROOT</replaceable></option></term>
 295
 296         <listitem><para>Use root directory <option>ROOT</option> when searching for coredumps.
 297         </para>
 298
 299         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 300       </varlistentry>
 301
 302       <varlistentry>
 303         <term><option>--image=<replaceable>image</replaceable></option></term>
 304
 305         <listitem><para>Takes a path to a disk image file or block device node. If specified, all operations
 306         are applied to file system in the indicated disk image. This option is similar to
 307         <option>--root=</option>, but operates on file systems stored in disk images or block devices. The
 308         disk image should either contain just a file system or a set of file systems within a GPT partition
 309         table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
 310         Specification</ulink>. For further information on supported disk images, see
 311         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 312         switch of the same name.</para>
 313
 314         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 315       </varlistentry>
 316
 317       <xi:include href="standard-options.xml" xpointer="image-policy-open" />
 318
 319       <varlistentry>
 320         <term><option>-q</option></term>
 321         <term><option>--quiet</option></term>
 322
 323         <listitem><para>Suppresses informational messages about lack
 324         of access to journal files and possible in-flight coredumps.
 325         </para>
 326
 327         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 328       </varlistentry>
 329
 330       <varlistentry>
 331         <term><option>--all</option></term>
 332
 333         <listitem><para>Look at all available journal files in <filename>/var/log/journal/</filename>
 334         (excluding journal namespaces) instead of only local ones.</para>
 335
 336         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 337       </varlistentry>
 338     </variablelist>
 339   </refsect1>
 340
 341   <refsect1>
 342     <title>Matching</title>
 343
 344     <para>A match can be:</para>
 345
 346     <variablelist>
 347       <varlistentry>
 348         <term><replaceable>PID</replaceable></term>
 349
 350         <listitem><para>Process ID of the
 351         process that dumped
 352         core. An integer.</para>
 353
 354         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 355       </varlistentry>
 356
 357       <varlistentry>
 358         <term><replaceable>COMM</replaceable></term>
 359
 360         <listitem><para>Name of the executable (matches
 361         <option>COREDUMP_COMM=</option>). Must not contain slashes.
 362         </para>
 363
 364         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 365       </varlistentry>
 366
 367       <varlistentry>
 368         <term><replaceable>EXE</replaceable></term>
 369
 370         <listitem><para>Path to the executable (matches
 371         <option>COREDUMP_EXE=</option>). Must contain at least one
 372         slash. </para>
 373
 374         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><replaceable>MATCH</replaceable></term>
 379
 380         <listitem><para>General journalctl match filter, must contain an equals
 381         sign (<literal>=</literal>). See
 382         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 383         </para>
 384
 385         <xi:include href="version-info.xml" xpointer="v215"/></listitem>
 386       </varlistentry>
 387     </variablelist>
 388   </refsect1>
 389
 390   <refsect1>
 391     <title>Exit status</title>
 392     <para>On success, 0 is returned; otherwise, a non-zero failure
 393     code is returned. Not finding any matching core dumps is treated as
 394     failure.
 395     </para>
 396   </refsect1>
 397
 398   <refsect1>
 399     <title>Environment</title>
 400
 401     <variablelist class='environment-variables'>
 402       <varlistentry>
 403         <term><varname>$SYSTEMD_DEBUGGER</varname></term>
 404         <listitem><para>Use the given debugger for the <command>debug</command>
 405         command. See the <option>--debugger=</option> option.</para>
 406
 407         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 408       </varlistentry>
 409     </variablelist>
 410   </refsect1>
 411
 412   <refsect1>
 413     <title>Examples</title>
 414
 415     <example>
 416       <title>List all the core dumps of a program</title>
 417
 418       <programlisting>$ coredumpctl list /usr/lib64/firefox/firefox
 419 TIME       PID  UID  GID SIG     COREFILE EXE                         SIZE
 420 Tue …   8018 1000 1000 SIGSEGV missing  /usr/lib64/firefox/firefox     -
 421 Wed … 251609 1000 1000 SIGTRAP missing  /usr/lib64/firefox/firefox     -
 422 Fri … 552351 1000 1000 SIGSEGV present  /usr/lib64/firefox/firefox 28.7M
 423 </programlisting>
 424
 425        <para>The journal has three entries pertaining to <filename>/usr/lib64/firefox/firefox</filename>, and
 426        only the last entry still has an available core file (in external storage on disk).</para>
 427
 428        <para>Note that <filename>coredumpctl</filename> needs access to the journal files to retrieve the
 429        relevant entries from the journal. Thus, an unprivileged user will normally only see information about
 430        crashing programs of this user.</para>
 431     </example>
 432
 433     <example>
 434       <title>Invoke <command>gdb</command> on the last core dump</title>
 435
 436       <programlisting>$ coredumpctl debug</programlisting>
 437     </example>
 438
 439     <example>
 440       <title>Use <command>gdb</command> to display full register info from the last core dump</title>
 441
 442       <programlisting>$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
 443     </example>
 444
 445     <example>
 446       <title>Show information about a core dump matched by PID</title>
 447
 448       <programlisting>$ coredumpctl info 6654
 449            PID: 6654 (bash)
 450            UID: 1000 (user)
 451            GID: 1000 (user)
 452         Signal: 11 (SEGV)
 453      Timestamp: Mon 2021-01-01 00:00:01 CET (20s ago)
 454   Command Line: bash -c $'kill -SEGV $$'
 455     Executable: /usr/bin/bash
 456  Control Group: /user.slice/user-1000.slice/…
 457           Unit: user@1000.service
 458      User Unit: vte-spawn-….scope
 459          Slice: user-1000.slice
 460      Owner UID: 1000 (user)
 461        Boot ID: …
 462     Machine ID: …
 463       Hostname: …
 464        Storage: /var/lib/systemd/coredump/core.bash.1000.….zst (present)
 465   Size on Disk: 51.7K
 466        Message: Process 130414 (bash) of user 1000 dumped core.
 467
 468                 Stack trace of thread 130414:
 469                 #0  0x00007f398142358b kill (libc.so.6 + 0x3d58b)
 470                 #1  0x0000558c2c7fda09 kill_builtin (bash + 0xb1a09)
 471                 #2  0x0000558c2c79dc59 execute_builtin.lto_priv.0 (bash + 0x51c59)
 472                 #3  0x0000558c2c79709c execute_simple_command (bash + 0x4b09c)
 473                 #4  0x0000558c2c798408 execute_command_internal (bash + 0x4c408)
 474                 #5  0x0000558c2c7f6bdc parse_and_execute (bash + 0xaabdc)
 475                 #6  0x0000558c2c85415c run_one_command.isra.0 (bash + 0x10815c)
 476                 #7  0x0000558c2c77d040 main (bash + 0x31040)
 477                 #8  0x00007f398140db75 __libc_start_main (libc.so.6 + 0x27b75)
 478                 #9  0x0000558c2c77dd1e _start (bash + 0x31d1e)
 479 </programlisting>
 480     </example>
 481
 482     <example>
 483       <title>Extract the last core dump of /usr/bin/bar to a file named
 484       <filename index="false">bar.coredump</filename></title>
 485
 486       <programlisting>$ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
 487     </example>
 488   </refsect1>
 489
 490   <refsect1>
 491     <title>See Also</title>
 492     <para><simplelist type="inline">
 493       <member><citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 494       <member><citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 495       <member><citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 496       <member><citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 497     </simplelist></para>
 498   </refsect1>
 499
 500 </refentry>