man/sysupdate.features.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sysupdate.features" conditional='ENABLE_SYSUPDATE'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sysupdate.features</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sysupdate.features</refentrytitle>
  16     <manvolnum>5</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sysupdate.features</refname>
  21     <refpurpose>Definition Files for Optional Features</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><simplelist>
  26       <member><filename>/etc/sysupdate.d/*.feature</filename></member>
  27       <member><filename>/run/sysupdate.d/*.feature</filename></member>
  28       <member><filename>/usr/local/lib/sysupdate.d/*.feature</filename></member>
  29       <member><filename>/usr/lib/sysupdate.d/*.feature</filename></member>
  30     </simplelist></para>
  31   </refsynopsisdiv>
  32
  33   <refsect1>
  34     <title>Description</title>
  35
  36     <para>"Optional Features" are functionality provided by
  37     <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  38     that allow a distribution to define sets of
  39     <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  40     transfer definitions that are intended to be enabled or disabled by the system administrator.</para>
  41
  42     <para>When a feature is enabled, transfers belonging to it will be considered when checking for and
  43     downloading updates, when vacuuming, and in all other situations.
  44     In effect, transfers belonging to a feature will always be updated in lock-step with the rest of their
  45     target.
  46     This is the primary difference an Optional Feature and a <command>systemd-sysupdate</command> component.
  47     When a feature is disabled, its transfers will not be considered when checking for and downloading updates,
  48     but <command>systemd-sysupdate</command> will still consider them while vacuuming and in other situations
  49     where it needs to determine ownership over previously downloaded system resources.
  50     <command>systemd-sysupdate</command> will clean up all instances of the feature's transfers whenever it
  51     is disabled, effectively uninstalling it.</para>
  52
  53     <para>Optional Features are described by <filename>sysupdate.d/*.feature</filename> files, which are
  54     defined below.
  55     Transfers can declare that they belong to a feature via the <varname>Features=</varname> setting.
  56     Feature definitions support drop-in files, which are most commonly used to override the
  57     <varname>Enabled=</varname> setting).
  58     They can also be masked out to hide the availability of the feature entirely.</para>
  59
  60     <para>Each <filename>*.feature</filename> file contains one section: [Feature].</para>
  61   </refsect1>
  62
  63   <refsect1>
  64     <title>[Feature] Section Options</title>
  65
  66     <para>This section defines general properties of this feature.</para>
  67
  68     <variablelist>
  69       <varlistentry>
  70         <term><varname>Description=</varname></term>
  71
  72         <listitem><para>A short human readable description of this feature.
  73         This may be used as a label for this feature, so the string should meaningfully identify the feature
  74         among the features available in <filename>sysupdate.d/</filename>.</para>
  75
  76         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
  77       </varlistentry>
  78
  79       <varlistentry>
  80         <term><varname>Documentation=</varname></term>
  81
  82         <listitem><para>A user-presentable URL to documentation about this feature.
  83         This setting supports specifier expansion; see below for details on supported specifiers.</para>
  84
  85         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><varname>AppStream=</varname></term>
  90
  91         <listitem><para>A URL to an
  92         <ulink url="https://www.freedesktop.org/software/appstream/docs/chap-CatalogData.html">AppStream catalog</ulink>
  93         XML file.
  94         This may be used by software centers (such as GNOME Software or KDE Discover) to present rich
  95         metadata about this feature.
  96         This includes display names, changelogs, icons, and more.
  97         This setting supports specifier expansion; see below for details on supported specifiers.</para>
  98
  99         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
 100       </varlistentry>
 101
 102       <varlistentry>
 103         <term><varname>Enabled=</varname></term>
 104
 105         <listitem><para>Whether or not this feature is enabled. If unspecified, the feature is disabled
 106         by default.</para>
 107
 108         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
 109       </varlistentry>
 110     </variablelist>
 111   </refsect1>
 112
 113   <refsect1>
 114     <title>Specifiers</title>
 115
 116     <para>Specifiers may be used in the <varname>Documentation=</varname> and <varname>AppStream=</varname>
 117     settings. The following expansions are understood:</para>
 118
 119     <table class='specifiers'>
 120       <title>Specifiers available</title>
 121       <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 122         <colspec colname="spec" />
 123         <colspec colname="mean" />
 124         <colspec colname="detail" />
 125         <thead>
 126           <row>
 127             <entry>Specifier</entry>
 128             <entry>Meaning</entry>
 129             <entry>Details</entry>
 130           </row>
 131         </thead>
 132         <tbody>
 133           <xi:include href="standard-specifiers.xml" xpointer="a"/>
 134           <xi:include href="standard-specifiers.xml" xpointer="A"/>
 135           <xi:include href="standard-specifiers.xml" xpointer="b"/>
 136           <xi:include href="standard-specifiers.xml" xpointer="B"/>
 137           <xi:include href="standard-specifiers.xml" xpointer="H"/>
 138           <xi:include href="standard-specifiers.xml" xpointer="l"/>
 139           <xi:include href="standard-specifiers.xml" xpointer="m"/>
 140           <xi:include href="standard-specifiers.xml" xpointer="M"/>
 141           <xi:include href="standard-specifiers.xml" xpointer="o"/>
 142           <xi:include href="standard-specifiers.xml" xpointer="v"/>
 143           <xi:include href="standard-specifiers.xml" xpointer="w"/>
 144           <xi:include href="standard-specifiers.xml" xpointer="W"/>
 145           <xi:include href="standard-specifiers.xml" xpointer="T"/>
 146           <xi:include href="standard-specifiers.xml" xpointer="V"/>
 147           <xi:include href="standard-specifiers.xml" xpointer="percent"/>
 148         </tbody>
 149       </tgroup>
 150     </table>
 151   </refsect1>
 152
 153   <refsect1>
 154     <title>Examples</title>
 155
 156     <example>
 157       <title>Development Tools for Image-Based OS</title>
 158
 159       <para>We'll use the hypothetical "foobarOS" described in
 160       <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> as our
 161       example base OS.
 162       The vast majority of foobarOS's users have no need for a compiler, build system, debugger, and other
 163       such development tools to be part of their OS.
 164       However, the developers of foobarOS itself need this build tooling to be available.
 165       So, foobarOS needs to provide a system extension image (see
 166       <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
 167       containing these development tools, and this image must be updated in lock-step with the underlying
 168       base OS.
 169       This is a great use case for an optional OS feature, so let's define one:
 170       </para>
 171
 172       <para><programlisting># /usr/lib/sysupdate.d/devel.feature
 173 [Feature]
 174 Description=Development Tools
 175 Documentation=https://developer.example.com/foobarOS/getting-started
 176 Enabled=false
 177 </programlisting></para>
 178
 179       <para>The above defines the <literal>devel</literal> feature, and disables it by default.
 180       Now let's define a transfer that's associated with this feature:</para>
 181
 182       <para><programlisting># /usr/lib/sysupdate.d/50-devel.transfer
 183 [Transfer]
 184 Features=devel
 185 ProtectVersion=%A
 186
 187 [Source]
 188 Type=url-file
 189 Path=https://download.example.com/
 190 MatchPattern=foobarOS_@v_devel.raw.xz
 191
 192 [Target]
 193 Type=regular-file
 194 Path=/var/lib/extensions
 195 MatchPattern=foobarOS_@v_devel.raw
 196 Mode=0444
 197 InstancesMax=2
 198 </programlisting></para>
 199
 200       <para>With these two files, we have created a feature called <literal>devel</literal> that, when
 201       enabled, will download and decompress the appropriate version of
 202       <literal>https://download.example.com/foobarOS_@v_devel.raw.xz</literal> into
 203       <literal>/var/lib/extensions/foobarOS_@v_devel.raw</literal> during each OS update.</para>
 204
 205       <para>The developers of foobarOS can enable the <literal>devel</literal> feature on their workstations
 206       by creating the following drop-in:</para>
 207
 208       <para><programlisting># /etc/sysupdate.d/devel.feature.d/enable.conf
 209 [Feature]
 210 Enabled=true
 211 </programlisting></para>
 212     </example>
 213
 214     <example>
 215       <title>Proprietary Drivers</title>
 216
 217       <para>Suppose that many of foobarOS's users have a GPU manufactured by the MVISUAL corporation.
 218       Due to lack of documentation and difficulty in reverse-engineering the hardware, the open-source
 219       drivers for MVISUAL GPUs are unable to make proper use of available graphics and compute performance.
 220       MVISUAL provides a redistributable proprietary driver for their cards, and foobarOS's developers
 221       distribute them to address their users' needs.</para>
 222
 223       <para>MVISUAL's driver has a couple different parts that must be installed for it to function: a UKI
 224       addon to configure the kernel command-line, an initrd system extension image to add the MVISUAL kernel
 225       module into the initrd, and a regular system extension image to add the proprietary OpenGL and Vulkan
 226       userspace drivers.
 227       All of these should be version-locked to the core OS.</para>
 228
 229       <para>Let's start by defining an optional feature named <literal>mvisual-driver</literal>:</para>
 230
 231       <para><programlisting># /usr/lib/sysupdate.d/mvisual-driver.feature
 232 [Feature]
 233 Description=MVISUAL Proprietary GPU Driver
 234 Documentation=https://support.example.com/foobarOS/mvisual
 235 AppStream=https://metadata.example.com/mvisual-driver-%A.xml.gz
 236 </programlisting></para>
 237
 238       <para>Note that we define AppStream metadata for this feature, because we want software centers to
 239       present it to end-users.
 240       Next, let's define the corresponding transfers:</para>
 241
 242       <para><programlisting># /usr/lib/sysupdate.d/50-mvisual-userspace.transfer
 243 [Transfer]
 244 Features=mvisual-driver
 245 ProtectVersion=%A
 246
 247 [Source]
 248 Type=url-file
 249 Path=https://download.example.com/
 250 MatchPattern=foobarOS_@v_mvisual_userspace.raw.xz
 251
 252 [Target]
 253 Type=regular-file
 254 Path=/var/lib/extensions
 255 MatchPattern=foobarOS_@v_mvisual.raw
 256 Mode=0444
 257 InstancesMax=2
 258 </programlisting></para>
 259
 260       <para><programlisting># /usr/lib/sysupdate.d/70-mvisual-initrd.transfer
 261 [Transfer]
 262 Features=mvisual-driver
 263 ProtectVersion=%A
 264
 265 [Source]
 266 Type=url-file
 267 Path=https://download.example.com/
 268 MatchPattern=foobarOS_@v_mvisual_initrd.raw.xz
 269
 270 [Target]
 271 Type=regular-file
 272 Path=/EFI/Linux
 273 PathRelativeTo=boot
 274 MatchPattern=foobarOS_@v.efi.extra.d/foobarOS_mvisual.raw
 275 Mode=0444
 276 InstancesMax=2
 277 </programlisting></para>
 278
 279       <para><programlisting># /usr/lib/sysupdate.d/90-mvisual-addon.transfer
 280 [Transfer]
 281 Features=mvisual-driver
 282 ProtectVersion=%A
 283
 284 [Source]
 285 Type=url-file
 286 Path=https://download.example.com/
 287 MatchPattern=foobarOS_@v_mvisual_addon.efi.xz
 288
 289 [Target]
 290 Type=regular-file
 291 Path=/EFI/Linux
 292 PathRelativeTo=boot
 293 MatchPattern=foobarOS_@v.efi.extra.d/foobarOS_mvisual.addon.efi
 294 Mode=0444
 295 InstancesMax=2
 296 </programlisting></para>
 297     </example>
 298
 299     <example>
 300       <title>Intersecting Features</title>
 301
 302       <para>Suppose that MVISUAL releases special tooling to help a distribution developer troubleshoot
 303       crashes in their proprietary driver.
 304       Let's define a transfer:</para>
 305
 306       <para><programlisting># /usr/lib/sysupdate.d/50-mvisual-debugger.transfer
 307 [Transfer]
 308 RequisiteFeatures=devel mvisual-driver
 309 ProtectVersion=%A
 310
 311 [Source]
 312 Type=url-file
 313 Path=https://download.example.com/
 314 MatchPattern=foobarOS_@v_devel.raw.xz
 315
 316 [Target]
 317 Type=regular-file
 318 Path=/var/lib/extensions
 319 MatchPattern=foobarOS_@v_devel.raw
 320 Mode=0444
 321 InstancesMax=2
 322 </programlisting></para>
 323
 324       <para>This transfer will be used only if both the <literal>devel</literal> and
 325       <literal>mvisual-driver</literal> features are enabled.</para>
 326     </example>
 327   </refsect1>
 328
 329   <refsect1>
 330     <title>See Also</title>
 331     <para><simplelist type="inline">
 332       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 333       <member><citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 334       <member><citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 335     </simplelist></para>
 336   </refsect1>
 337
 338 </refentry>