man/sysupdate.components.xml - main - niceSOFT/systemd

man/sysupdate.components.xml
292 строки14 KB
Lennart Poettering
man: document the new .component files
15 июл 2026, 14:27
15 июл 2026, 14:2787f4e72
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="sysupdate.components" conditional='ENABLE_SYSUPDATE'
          xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>sysupdate.components</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sysupdate.components</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sysupdate.components</refname>
    <refpurpose>Definition Files for Update Components</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><simplelist>
      <member><filename>/etc/sysupdate.<replaceable>component</replaceable>.component</filename></member>
      <member><filename>/run/sysupdate.<replaceable>component</replaceable>.component</filename></member>
      <member><filename>/usr/local/lib/sysupdate.<replaceable>component</replaceable>.component</filename></member>
      <member><filename>/usr/lib/sysupdate.<replaceable>component</replaceable>.component</filename></member>
    </simplelist></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>A "Component" is a set of
    <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    transfer definitions that
    <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    updates independently from the rest of the OS.
    Each component is a self-contained installation with its own version, and its own set of transfer files,
    stored in a directory named after the component:
    <filename>sysupdate.<replaceable>component</replaceable>.d/*.transfer</filename> (as opposed to the
    default, component-less <filename>sysupdate.d/*.transfer</filename>).
    Components are selected via the <option>--component=</option>, <option>--component-all</option> or
    <option>--component-suggested</option> switches of
    <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and
    enumerated by its <command>components</command> command.</para>

    <para>Because components are updated separately, they are the right tool for OS resources that shall be
    versioned and updated independently from the base OS — for example a container image or a portable service
    image that follows its own release cycle. This is the primary difference between a component and an
    <citerefentry><refentrytitle>sysupdate.features</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    Optional Feature: the transfers belonging to a feature are updated in lock-step with the target they are
    part of, while a component is a wholly separate installation. Do not use a component for resources that
    shall always be updated synchronously with something else; use a feature (or simply additional transfer
    files in the same directory) for those cases.</para>

    <para>A component does not require a <filename>*.component</filename> file: as soon as a matching
    <filename>sysupdate.<replaceable>component</replaceable>.d/</filename> directory with transfer definitions
    exists, the component is available for updating. The <filename>*.component</filename> file described here
    is optional, and carries metadata about the component (such as a human-readable description and a
    documentation URL) as well as its enablement state.</para>

    <para>When a component is disabled (via <varname>Enabled=false</varname>, see below), operations that
    would download or install new versions — most importantly <command>update</command> — refuse to act on
    it. Other operations, such as <command>vacuum</command> and <command>cleanup</command>, continue to
    consider the component's transfers so that previously installed instances remain managed and can be
    cleaned up. Components are enabled or disabled with the <command>enable-component</command> and
    <command>disable-component</command> commands of
    <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
    which write an <varname>Enabled=</varname> setting into a drop-in next to the component definition.</para>

    <para>Component definitions support drop-in files, which are most commonly used to override the
    <varname>Enabled=</varname> setting. Drop-ins are read from
    <filename>sysupdate.<replaceable>component</replaceable>.component.d/*.conf</filename> in the same set of
    directories as the main file. They can also be masked to hide the component definition entirely.</para>

    <para>Each <filename>*.component</filename> file contains one section: [Component].</para>
  </refsect1>

  <refsect1>
    <title>[Component] Section Options</title>

    <para>This section defines general properties of this component.</para>

    <variablelist>
      <varlistentry>
        <term><varname>Description=</varname></term>

        <listitem><para>A short human-readable description of this component.
        This may be used as a label for this component, so the string should meaningfully identify the
        component among the components available on the system.</para>

        <xi:include href="version-info.xml" xpointer="v262"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>Documentation=</varname></term>

        <listitem><para>A user-presentable URL to documentation about this component.
        This setting supports specifier expansion; see below for details on supported specifiers.</para>

        <xi:include href="version-info.xml" xpointer="v262"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>Enabled=</varname></term>

        <listitem><para>Whether or not this component is enabled. If unspecified, the component is enabled
        by default. When disabled, <command>systemd-sysupdate</command> refuses to download or install new
        versions of this component, but continues to consider its transfers while vacuuming and in other
        situations where it needs to determine ownership over previously downloaded system resources.</para>

        <xi:include href="version-info.xml" xpointer="v262"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>Suggest=</varname></term>

        <listitem><para>Takes a boolean argument. If true, this component is suggested for enablement, if
        false it is not. This does not enable the component on its own, but is a hint surfaced by the update
        tools (for example via the <option>--component-suggested</option> switch of
        <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
        so that the system administrator or higher-level tooling may act on it.</para>

        <para>If this setting is not specified, the <varname>SuggestOn…=</varname> conditions described below
        are evaluated instead to determine whether the component is suggested. If neither this setting nor any
        <varname>SuggestOn…=</varname> condition is specified, the component is not suggested.</para>

        <xi:include href="version-info.xml" xpointer="v262"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>SuggestOnArchitecture=</varname></term>
        <term><varname>SuggestOnFirmware=</varname></term>
        <term><varname>SuggestOnVirtualization=</varname></term>
        <term><varname>SuggestOnHost=</varname></term>
        <term><varname>SuggestOnFraction=</varname></term>
        <term><varname>SuggestOnKernelCommandLine=</varname></term>
        <term><varname>SuggestOnVersion=</varname></term>
        <term><varname>SuggestOnCredential=</varname></term>
        <term><varname>SuggestOnSecurity=</varname></term>
        <term><varname>SuggestOnOSRelease=</varname></term>
        <term><varname>SuggestOnMachineTag=</varname></term>

        <listitem><para>Suggest this component for enablement depending on system properties. These settings
        take the same arguments and implement the same semantics — including the leading <literal>!</literal>
        for negation — as the identically-named
        <varname>ConditionArchitecture=</varname>, <varname>ConditionFirmware=</varname>,
        <varname>ConditionVirtualization=</varname>, <varname>ConditionHost=</varname>,
        <varname>ConditionFraction=</varname>, <varname>ConditionKernelCommandLine=</varname>,
        <varname>ConditionVersion=</varname>, <varname>ConditionCredential=</varname>,
        <varname>ConditionSecurity=</varname>, <varname>ConditionOSRelease=</varname> and
        <varname>ConditionMachineTag=</varname> settings for unit files, which are documented in
        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
        The component is suggested if all specified conditions apply. As with the <varname>Condition…=</varname>
        settings, assigning an empty string to one of these resets the list.</para>

        <para>These conditions are only evaluated if <varname>Suggest=</varname> is not specified.</para>

        <xi:include href="version-info.xml" xpointer="v262"/></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Specifiers</title>

    <para>Specifiers may be used in the <varname>Documentation=</varname> setting. The following expansions
    are understood:</para>

    <table class='specifiers'>
      <title>Specifiers available</title>
      <tgroup cols='3' align='left' colsep='1' rowsep='1'>
        <colspec colname="spec" />
        <colspec colname="mean" />
        <colspec colname="detail" />
        <thead>
          <row>
            <entry>Specifier</entry>
            <entry>Meaning</entry>
            <entry>Details</entry>
          </row>
        </thead>
        <tbody>
          <xi:include href="standard-specifiers.xml" xpointer="a"/>
          <xi:include href="standard-specifiers.xml" xpointer="A"/>
          <xi:include href="standard-specifiers.xml" xpointer="b"/>
          <xi:include href="standard-specifiers.xml" xpointer="B"/>
          <xi:include href="standard-specifiers.xml" xpointer="H"/>
          <xi:include href="standard-specifiers.xml" xpointer="l"/>
          <xi:include href="standard-specifiers.xml" xpointer="m"/>
          <xi:include href="standard-specifiers.xml" xpointer="M"/>
          <xi:include href="standard-specifiers.xml" xpointer="o"/>
          <xi:include href="standard-specifiers.xml" xpointer="v"/>
          <xi:include href="standard-specifiers.xml" xpointer="w"/>
          <xi:include href="standard-specifiers.xml" xpointer="W"/>
          <xi:include href="standard-specifiers.xml" xpointer="T"/>
          <xi:include href="standard-specifiers.xml" xpointer="V"/>
          <xi:include href="standard-specifiers.xml" xpointer="percent"/>
        </tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <example>
      <title>A Separately Updated Container Image</title>

      <para>We'll use the hypothetical "foobarOS" described in
      <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> as our
      example base OS.
      foobarOS ships a container image that many, but not all, deployments want to run. The image has its own
      release cadence and version number, entirely separate from the base OS, so it is a poor fit for an
      Optional Feature (which would be version-locked to the OS). Instead, let's model it as a component named
      <literal>webapp</literal>.</para>

      <para>First, the component definition, carrying its metadata and marking it as disabled by default:</para>

      <para><programlisting># /usr/lib/sysupdate.webapp.component
[Component]
Description=WebApp Container Image
Documentation=https://docs.example.com/foobarOS/webapp
Enabled=false
</programlisting></para>

      <para>Next, the transfer definition for the component, placed in the component's own directory
      <filename>sysupdate.webapp.d/</filename>:</para>

      <para><programlisting># /usr/lib/sysupdate.webapp.d/50-webapp.transfer
[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=webapp_@v.raw.xz

[Target]
Type=regular-file
Path=/var/lib/machines
MatchPattern=webapp_@v.raw
Mode=0444
InstancesMax=2
</programlisting></para>

      <para>With these two files, updates for the <literal>webapp</literal> component can be checked and
      downloaded independently of the base OS, for example with
      <command>systemd-sysupdate --component=webapp update</command>. Because
      <varname>Enabled=false</varname> was set, the administrator must first opt in with
      <command>systemd-sysupdate enable-component webapp</command>, which writes the following drop-in:</para>

      <para><programlisting># /etc/sysupdate.webapp.component.d/50-systemd-sysupdate-enabled.conf
# Generated via 'systemd-sysupdate enable-component'

[Component]
Enabled=true
</programlisting></para>
    </example>

    <example>
      <title>A Component Suggested Only on Bare Metal</title>

      <para>Suppose foobarOS ships a component with firmware and microcode updates that is only relevant when
      running on physical hardware, not inside a virtual machine. We can use <varname>SuggestOn…=</varname> to
      hint that the component should be enabled in that case, without enabling it automatically:</para>

      <para><programlisting># /usr/lib/sysupdate.firmware.component
[Component]
Description=Firmware and Microcode Updates
Documentation=https://docs.example.com/foobarOS/firmware
Enabled=false
SuggestOnVirtualization=!vm
</programlisting></para>

      <para>Higher-level tooling can now query the suggested components (via
      <command>systemd-sysupdate --component-suggested …</command>) and enable them as appropriate. On bare
      metal the <literal>firmware</literal> component is suggested; inside a VM it is not.</para>
    </example>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>sysupdate.features</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>

</refentry>