man/systemd-debug-generator.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   5 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   6 %entities;
   7 ]>
   8 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   9 <refentry id="systemd-debug-generator" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>systemd-debug-generator</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>systemd-debug-generator</refentrytitle>
  18     <manvolnum>8</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>systemd-debug-generator</refname>
  23     <refpurpose>Generator for enabling a runtime debug shell and
  24     masking specific units at boot</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <para><filename>/usr/lib/systemd/system-generators/systemd-debug-generator</filename></para>
  29   </refsynopsisdiv>
  30
  31   <refsect1>
  32     <title>Description</title>
  33
  34     <para><filename>systemd-debug-generator</filename> is a generator
  35     that reads the kernel command line and understands three
  36     options:</para>
  37
  38     <para>If the <option>systemd.mask=</option> or <option>rd.systemd.mask=</option>
  39     option is specified and followed by a unit name, this unit is
  40     masked for the runtime (i.e. for this session — from boot to shutdown), similarly to the effect of
  41     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
  42     <command>mask</command> command. This is useful to boot with
  43     certain units removed from the initial boot transaction for
  44     debugging system startup. May be specified more than once.
  45     <option>rd.systemd.mask=</option> is honored only by initial
  46     RAM disk (initrd) while <option>systemd.mask=</option> is
  47     honored only in the main system.</para>
  48
  49     <para>If the <option>systemd.wants=</option> or
  50     <option>rd.systemd.wants=</option> option is specified
  51     and followed by a unit name, a start job for this unit is added to
  52     the initial transaction. This is useful to start one or more
  53     additional units at boot. May be specified more than once.
  54     <option>rd.systemd.wants=</option> is honored only by initial
  55     RAM disk (initrd) while <option>systemd.wants=</option> is
  56     honored only in the main system.</para>
  57
  58     <para>If the <option>systemd.debug_shell</option> or <option>rd.systemd.debug_shell</option> option is
  59     specified, the debug shell service <literal>debug-shell.service</literal> is pulled into the boot
  60     transaction and a debug shell will be spawned during early boot. By default,
  61     <filename>&DEBUGTTY;</filename> is used, but a specific tty can also be specified, either with or without
  62     the <filename>/dev/</filename> prefix. To set the tty to use without enabling the debug shell, the
  63     <option>systemd.default_debug_tty=</option> option can be used which also takes a tty with or without the
  64     <filename>/dev/</filename> prefix. Note that the shell may also be turned on persistently by enabling it
  65     with <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
  66     <command>enable</command> command. <option>rd.systemd.debug_shell</option> is honored only by initial
  67     RAM disk (initrd) while <option>systemd.debug_shell</option> is honored only in the main system.</para>
  68
  69     <para><filename>systemd-debug-generator</filename> implements
  70     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
  71   </refsect1>
  72
  73   <refsect1>
  74     <title>System Credentials</title>
  75
  76     <variablelist class='system-credentials'>
  77       <varlistentry>
  78         <term><varname>systemd.extra-unit.*</varname></term>
  79
  80         <listitem><para>Credentials prefixed with <literal>systemd.extra-unit.</literal> specify additional
  81         units to add to the final system. Note that these additional units are added to both the initrd and
  82         the final system. <varname>ConditionPathExists=!/etc/initrd-release</varname> can be used to make
  83         sure the unit is conditioned out in the initrd.</para>
  84
  85         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><varname>systemd.unit-dropin.*</varname></term>
  90
  91         <listitem><para>Credentials prefixed with <literal>systemd.unit-dropin.</literal> add drop-ins for
  92         the corresponding units in the final system. Each credential must be suffixed with the full unit name
  93         including the unit extension. Its contents must be a valid unit drop-in file. Only one drop-in per
  94         unit can be specified. The name of the generated drop-in will be
  95         <literal>50-credential.conf</literal>. Note that these additional drop-ins are added to both the
  96         initrd and the final system.</para>
  97
  98         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
  99       </varlistentry>
 100     </variablelist>
 101   </refsect1>
 102
 103   <refsect1>
 104     <title>See Also</title>
 105     <para><simplelist type="inline">
 106       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 107       <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 108       <member><citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 109     </simplelist></para>
 110   </refsect1>
 111
 112 </refentry>