debuginfod.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter
[
  <!ENTITY % entities SYSTEM "generic-entities.ent">
    %entities;
]>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="debuginfo">
 <title>Getting debugging data and sources with &debuginfod;</title>
 <info>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
   <dm:bugtracker></dm:bugtracker>
   <dm:translation>yes</dm:translation>
  </dm:docmanager>
 </info>
 <sect1 xml:id="debuginfo-introduction">
  <title>Introduction</title>

  <para>
   Developers often need to solve bugs in software packages. Debugging tools,
   for example GDB, use information contained in special files that are not
   available in the installed binary version of the package. It is available in
   the <emphasis>debugsource</emphasis> or <emphasis>debuginfo</emphasis> version of the package.
   Installing packages with extended debugging information requires system
   administrator privileges and occupies a lot of disk space.
  </para>

  <para>
   The &debuginfod; service contains an HTTP file server that provides
   debugging information for debugging tools without the need to install
   debuginfo versions of packages.
  </para>
 </sect1>
 <sect1 xml:id="debuginfo-how-it-works">
  <title>How &debuginfod; works</title>

  <para>
   &debuginfod; periodically scans remote and local directory trees and RPM
   package archives to extract the build IDs of discovered executables and
   debuginfo files. It stores these IDs into a built-in database and indexes
   them to the related file or package names.
  </para>
 </sect1>
 <sect1 xml:id="debuginfo-configuration">
  <title>Configuring &debuginfod;</title>

  <para>
   You can query external &debuginfod; servers, run local &debuginfod; server,
   or a combination of both approaches.
  </para>

  <sect2 xml:id="debuginfo-configuration-local">
   <title>Runing local &debuginfod; server</title>
   <para>
    To run a local &debuginfod; server, follow these steps:
   </para>
   <procedure>
    <step>
     <para>
      Install the <package>elfutils-debuginfod</package> package:
     </para>
<screen>&prompt.sudo;zypper install elfutils-debuginfod</screen>
    </step>
    <step>
     <para>
      Start the &debuginfod; service:
     </para>
<screen>&prompt.sudo;systemctl start debuginfod.service</screen>
    </step>
    <step>
     <para>
      Add the local server's URL to the <varname>DEBUGINFOD_URLS</varname>
      environment variable:
     </para>
<screen>&prompt.sudo;export DEBUGINFOD_URLS="http://localhost:8002/ $DEBUGINFOD_URLS"</screen>
    </step>
   </procedure>
  </sect2>

  <sect2 xml:id="debuginfo-configuration-remote">
   <title>Adding remote &debuginfod; servers</title>
   <para>
    To be able to query remote &debuginfod; server, add its URL to the
    <varname>DEBUGINFOD_URLS</varname> environment variable. For example:
   </para>
<screen>&prompt.sudo;export DEBUGINFOD_URLS="https://debuginfod.opensuse.org/ $DEBUGINFOD_URLS"</screen>
  </sect2>
 </sect1>
 <sect1 xml:id="debuginfo-usage">
  <title>Querying executables for debugging information</title>

  <para>
   The <command>debuginfod-find</command> command&mdash;which is part of the
   <package>debuginfod-client</package> package&mdash;queries configured
   &debuginfod; servers for debugging information. It uses build IDs to
   identify the queried data. For example, for an executable
   <filename>/bin/ls</filename>, you can find the build ID by running the
   following command and the query for the debugging information:
  </para>

<screen>
&prompt.user;readelf -n /bin/ls | grep 'Build ID'
Build ID: e21f1b05e314b4c54ee57ec057c4f40c1df49dd3
&prompt.user;debuginfod-find debuginfo e21f1b05e314b4c54ee57ec057c4f40c1df49dd3
/root/.cache/debuginfod_client/e21f1b05e314b4c54ee57ec057c4f40c1df49dd3/debuginfo
</screen>
 </sect1>
</chapter>