man: various updates to the bootctl man page

[thirdparty/systemd.git] / man / bootctl.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!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="bootctl" conditional='ENABLE_EFI'
    xmlns:xi="http://www.w3.org/2001/XInclude">
  <refentryinfo>
    <title>bootctl</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>bootctl</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>bootctl</refname>
    <refpurpose>Control the firmware and boot manager settings</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>bootctl</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="req">COMMAND</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>bootctl</command> can check the EFI boot loader status, list available boot loaders and boot loader
    entries, and install, update, or remove the
    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> boot loader on the
    current system.</para>
  </refsect1>

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

    <variablelist>
      <varlistentry>
        <term><option>--path=</option></term>
        <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi</filename>,
        <filename>/boot</filename>, and <filename>/boot/efi</filename> are checked in turn.  It is recommended to mount
        the ESP to <filename>/boot</filename>, if possible.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-p</option></term>
        <term><option>--print-path</option></term>
        <listitem><para>This option modifies the behaviour of <command>status</command>.
        Just print the path to the EFI System Partition (ESP) to standard output and
        exit.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--no-variables</option></term>
        <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para></listitem>
      </varlistentry>

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

  <refsect1>
    <title>Commands</title>
    <variablelist>

      <varlistentry>
        <term><option>status</option></term>

        <listitem><para>Shows brief information about the system firmware, the boot loader that was used to boot the
        system, the boot loaders currently available in the ESP, the boot loaders listed in the firmware's list of boot
        loaders and the current default boot loader entry. If no command is specified, this is the implied
        default.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>list</option></term>

        <listitem><para>Shows all available boot loader entries implementing the <ulink
        url="https://github.com/systemd/systemd/blob/master/docs/BOOT_LOADER_SPECIFICATION.md">Boot Loader
        Specification</ulink>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>install</option></term>

        <listitem><para>Installs systemd-boot into the EFI system partition. A copy of <command>systemd-boot</command>
        will be stored as the EFI default/fallback loader at
        <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added to the
        top of the firmware's boot loader list.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>update</option></term>

        <listitem><para>Updates all installed versions of
        <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the
        available version is newer than the version installed in the EFI system partition. This also includes the EFI
        default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot
        loader is then added to end of the firmware's boot loader list if missing.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>remove</option></term>

        <listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition
        and the firmware's boot loader list.</para></listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>Exit status</title>
    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
      <ulink url="https://github.com/systemd/systemd/blob/master/docs/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>,
      <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
    </para>
  </refsect1>
</refentry>