[thirdparty/systemd.git] / man / kernel-install.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  SPDX-License-Identifier: LGPL-2.1+
-->

<refentry id="kernel-install"
          xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>kernel-install</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>kernel-install</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>kernel-install</refname>
    <refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>kernel-install</command>
      <arg choice="plain">COMMAND</arg>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
      <arg choice="plain"><replaceable>KERNEL-IMAGE</replaceable></arg>
      <arg choice="opt" rep="repeat"><replaceable>INITRD-FILE</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <command>kernel-install</command> is used to install and remove kernel and
      initramfs images to and from <filename>/boot</filename>.
    </para>

    <para><command>kernel-install</command> will execute the files
    located in the directory <filename>/usr/lib/kernel/install.d/</filename>
    and the local administration directory <filename>/etc/kernel/install.d/</filename>.
    All files are collectively sorted and executed in lexical order, regardless of the directory in
    which they live. However, files with identical filenames replace each other.
    Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the same name
    in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied
    executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename>
    with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>,
    pointing to <filename>/dev/null</filename>, disables the executable entirely. Executables must have the
    extension <literal>.install</literal>; other extensions are ignored.</para>

    <para>An executable should return <constant>0</constant> on success. It may also
    return <constant>77</constant> to cause the whole operation to terminate
    (executables later in lexical order will be skipped).</para>
  </refsect1>

  <refsect1>
    <title>Commands</title>
    <para>The following commands are understood:</para>
    <variablelist>
      <varlistentry>
        <term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</command></term>
        <listitem>
          <para>This command expects a kernel version string and a path to a kernel image file as
          arguments. <command>kernel-install</command> calls the executables from
          <filename>/usr/lib/kernel/install.d/*.install</filename> and
          <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:

          <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</programlisting>
          </para>

          <para>Three default plugins execute the following operations in this case:</para>

          <itemizedlist>
            <listitem><para><filename>00-entry-directory.install</filename> creates the directory
            <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
            if <filename>/boot/<replaceable>MACHINE-ID</replaceable>/</filename> already exists.
            </para></listitem>

            <listitem><para><filename>50-depmod.install</filename> runs
            <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
            <replaceable>KERNEL-VERSION</replaceable>.</para></listitem>

            <listitem><para><filename>90-loaderentry.install</filename> copies <replaceable>KERNEL-IMAGE</replaceable>
            to
            <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
            If an <replaceable>INITRD-FILE</replaceable> is provided, it also copies <replaceable>INITRD-FILE</replaceable>
            to
            <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
            It also creates a boot loader entry according to the <ulink
            url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> in
            <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
            The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
            <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former is
            missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para>

            <para>If the entry directory
            <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
            does not exist, this plugin does nothing.</para></listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
        <listitem>
          <para>This command expects a kernel version string as single argument. This calls executables from
          <filename>/usr/lib/kernel/install.d/*.install</filename> and
          <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:

          <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
          </para>

          <para>Afterwards, <command>kernel-install</command> removes the directory
          <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
          and its contents.</para>

          <para>Two default plugins execute the following operations in this case:</para>

          <itemizedlist>

            <listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem>

            <listitem><para><filename>90-loaderentry.install</filename> removes the file
            <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem>
          </itemizedlist>

        </listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>Options</title>
    <para>The following options are understood:</para>

    <variablelist>
      <varlistentry>
        <term><option>-v</option></term>
        <term><option>--verbose</option></term>
        <listitem>
          <para>Output additional information about operations being performed.</para>
        </listitem>
      </varlistentry>

      <xi:include href="standard-options.xml" xpointer="help" />
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Environment variables</title>
    <para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be set for
    the plugins. They may output additional logs in this case.</para>
  </refsect1>

  <refsect1>
    <title>Exit status</title>
    <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
  </refsect1>

  <refsect1>
    <title>Files</title>
    <variablelist>
      <varlistentry>
        <term>
          <filename>/usr/lib/kernel/install.d/*.install</filename>
          <filename>/etc/kernel/install.d/*.install</filename>
        </term>
          <listitem>
            <para>Drop-in files which are executed by kernel-install.</para>
          </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <filename>/etc/kernel/cmdline</filename>
          <filename>/proc/cmdline</filename>
        </term>
          <listitem>
            <para>Read by <filename>90-loaderentry.install</filename>. The content of the file
            <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.  If that file does not
            exist, <filename>/proc/cmdline</filename> is used.</para>
          </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <filename>/etc/kernel/tries</filename>
        </term>
          <listitem>
            <para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from
            it and the naming of the generated entry file is slightly altered to include it as
            <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This
            is useful for boot loaders such as
            <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
            implement boot attempt counting with a counter embedded in the entry file name.</para>
          </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <filename>/etc/machine-id</filename>
        </term>
          <listitem>
            <para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
          </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <filename>/etc/os-release</filename>
          <filename>/usr/lib/os-release</filename>
        </term>
          <listitem>
            <para>The content of the file specifies the operating system title <replaceable>PRETTY_NAME</replaceable>.</para>
          </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
      <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
    </para>
  </refsect1>

</refentry>
Commit	Line	Data
514094f9	1	<?xml version='1.0'?>
81516adc	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
81516adc HH	4
81516adc HH	5	<!--
572eb058	6	SPDX-License-Identifier: LGPL-2.1+
81516adc HH	7	-->
81516adc HH	8
7054308a ZJS	9	<refentry id="kernel-install"
7054308a ZJS	10	xmlns:xi="http://www.w3.org/2001/XInclude">
81516adc HH	11
	12	<refentryinfo>
	13	<title>kernel-install</title>
	14	<productname>systemd</productname>
81516adc HH	15	</refentryinfo>
	16
	17	<refmeta>
	18	<refentrytitle>kernel-install</refentrytitle>
	19	<manvolnum>8</manvolnum>
	20	</refmeta>
	21
	22	<refnamediv>
	23	<refname>kernel-install</refname>
	24	<refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose>
	25	</refnamediv>
	26
	27	<refsynopsisdiv>
	28	<cmdsynopsis>
845c5324 ZJS	29	<command>kernel-install</command>
845c5324 ZJS	30	<arg choice="plain">COMMAND</arg>
7054308a	31	<arg choice="opt" rep="repeat">OPTIONS</arg>
845c5324	32	<arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
04ca4d19	33	<arg choice="plain"><replaceable>KERNEL-IMAGE</replaceable></arg>
0912c0b8	34	<arg choice="opt" rep="repeat"><replaceable>INITRD-FILE</replaceable></arg>
81516adc HH	35	</cmdsynopsis>
	36	</refsynopsisdiv>
	37
	38	<refsect1>
	39	<title>Description</title>
	40	<para>
	41	<command>kernel-install</command> is used to install and remove kernel and
	42	initramfs images to and from <filename>/boot</filename>.
	43	</para>
	44
845c5324 ZJS	45	<para><command>kernel-install</command> will execute the files
845c5324 ZJS	46	located in the directory <filename>/usr/lib/kernel/install.d/</filename>
81516adc	47	and the local administration directory <filename>/etc/kernel/install.d/</filename>.
845c5324	48	All files are collectively sorted and executed in lexical order, regardless of the directory in
e9dd9f95	49	which they live. However, files with identical filenames replace each other.
81516adc HH	50	Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the same name
	51	in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied
	52	executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename>
	53	with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>,
eb933128	54	pointing to <filename>/dev/null</filename>, disables the executable entirely. Executables must have the
409dee2e	55	extension <literal>.install</literal>; other extensions are ignored.</para>
81516adc	56
eb933128 ZJS	57	<para>An executable should return <constant>0</constant> on success. It may also
	58	return <constant>77</constant> to cause the whole operation to terminate
	59	(executables later in lexical order will be skipped).</para>
81516adc HH	60	</refsect1>
	61
	62	<refsect1>
	63	<title>Commands</title>
	64	<para>The following commands are understood:</para>
	65	<variablelist>
	66	<varlistentry>
0912c0b8	67	<term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</command></term>
81516adc	68	<listitem>
4b2d80bb	69	<para>This command expects a kernel version string and a path to a kernel image file as
cf73f650 ZJS	70	arguments. <command>kernel-install</command> calls the executables from
cf73f650 ZJS	71	<filename>/usr/lib/kernel/install.d/*.install</filename> and
4b2d80bb LP	72	<filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
4b2d80bb LP	73
0912c0b8	74	<programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</programlisting>
845c5324 ZJS	75	</para>
845c5324 ZJS	76
cf73f650	77	<para>Three default plugins execute the following operations in this case:</para>
4b2d80bb LP	78
4b2d80bb LP	79	<itemizedlist>
cf73f650 ZJS	80	<listitem><para><filename>00-entry-directory.install</filename> creates the directory
	81	<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
	82	if <filename>/boot/<replaceable>MACHINE-ID</replaceable>/</filename> already exists.
	83	</para></listitem>
4b2d80bb LP	84
	85	<listitem><para><filename>50-depmod.install</filename> runs
	86	<citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
	87	<replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
	88
	89	<listitem><para><filename>90-loaderentry.install</filename> copies <replaceable>KERNEL-IMAGE</replaceable>
	90	to
	91	<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
0912c0b8	92	If an <replaceable>INITRD-FILE</replaceable> is provided, it also copies <replaceable>INITRD-FILE</replaceable>
04ca4d19	93	to
0912c0b8	94	<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
4b2d80bb LP	95	It also creates a boot loader entry according to the <ulink
	96	url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> in
	97	<filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
	98	The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
	99	<filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former is
cf73f650 ZJS	100	missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para>
	101
	102	<para>If the entry directory
	103	<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
	104	does not exist, this plugin does nothing.</para></listitem>
4b2d80bb	105	</itemizedlist>
81516adc HH	106	</listitem>
	107	</varlistentry>
	108	<varlistentry>
8f51399e	109	<term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
845c5324	110	<listitem>
4b2d80bb LP	111	<para>This command expects a kernel version string as single argument. This calls executables from
	112	<filename>/usr/lib/kernel/install.d/*.install</filename> and
	113	<filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
	114
9fccdb0f	115	<programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
845c5324 ZJS	116	</para>
845c5324 ZJS	117
4b2d80bb LP	118	<para>Afterwards, <command>kernel-install</command> removes the directory
	119	<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
	120	and its contents.</para>
	121
	122	<para>Two default plugins execute the following operations in this case:</para>
	123
	124	<itemizedlist>
	125
	126	<listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem>
	127
	128	<listitem><para><filename>90-loaderentry.install</filename> removes the file
	129	<filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem>
	130	</itemizedlist>
8f51399e	131
81516adc HH	132	</listitem>
	133	</varlistentry>
	134
	135	</variablelist>
	136
	137	</refsect1>
	138
7054308a ZJS	139	<refsect1>
	140	<title>Options</title>
	141	<para>The following options are understood:</para>
	142
	143	<variablelist>
	144	<varlistentry>
	145	<term><option>-v</option></term>
	146	<term><option>--verbose</option></term>
	147	<listitem>
	148	<para>Output additional information about operations being performed.</para>
	149	</listitem>
	150	</varlistentry>
	151
	152	<xi:include href="standard-options.xml" xpointer="help" />
	153	</variablelist>
	154	</refsect1>
	155
	156	<refsect1>
	157	<title>Environment variables</title>
	158	<para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be set for
	159	the plugins. They may output additional logs in this case.</para>
	160	</refsect1>
	161
81516adc HH	162	<refsect1>
81516adc HH	163	<title>Exit status</title>
c4c50112	164	<para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
81516adc HH	165	</refsect1>
	166
	167	<refsect1>
	168	<title>Files</title>
	169	<variablelist>
	170	<varlistentry>
	171	<term>
	172	<filename>/usr/lib/kernel/install.d/*.install</filename>
	173	<filename>/etc/kernel/install.d/*.install</filename>
	174	</term>
	175	<listitem>
409dee2e	176	<para>Drop-in files which are executed by kernel-install.</para>
81516adc HH	177	</listitem>
81516adc HH	178	</varlistentry>
2d0614d3 HH	179	<varlistentry>
	180	<term>
	181	<filename>/etc/kernel/cmdline</filename>
	182	<filename>/proc/cmdline</filename>
	183	</term>
	184	<listitem>
4b2d80bb LP	185	<para>Read by <filename>90-loaderentry.install</filename>. The content of the file
	186	<filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use. If that file does not
	187	exist, <filename>/proc/cmdline</filename> is used.</para>
	188	</listitem>
	189	</varlistentry>
	190	<varlistentry>
	191	<term>
	192	<filename>/etc/kernel/tries</filename>
	193	</term>
	194	<listitem>
	195	<para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from
	196	it and the naming of the generated entry file is slightly altered to include it as
	197	<filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This
	198	is useful for boot loaders such as
	199	<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
	200	implement boot attempt counting with a counter embedded in the entry file name.</para>
2d0614d3 HH	201	</listitem>
	202	</varlistentry>
	203	<varlistentry>
	204	<term>
	205	<filename>/etc/machine-id</filename>
	206	</term>
	207	<listitem>
845c5324	208	<para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
2d0614d3 HH	209	</listitem>
	210	</varlistentry>
	211	<varlistentry>
	212	<term>
	213	<filename>/etc/os-release</filename>
5ae4d543	214	<filename>/usr/lib/os-release</filename>
2d0614d3 HH	215	</term>
2d0614d3 HH	216	<listitem>
8f51399e	217	<para>The content of the file specifies the operating system title <replaceable>PRETTY_NAME</replaceable>.</para>
2d0614d3 HH	218	</listitem>
2d0614d3 HH	219	</varlistentry>
81516adc HH	220	</variablelist>
	221	</refsect1>
	222
	223	<refsect1>
	224	<title>See Also</title>
	225	<para>
2d0614d3 HH	226	<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
2d0614d3 HH	227	<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
4b2d80bb LP	228	<citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
4b2d80bb LP	229	<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
a0848495	230	<ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
81516adc HH	231	</para>
	232	</refsect1>
	233
	234	</refentry>