'\" t
.TH "SYSUPDATE\&.FEATURES" "5" "" "systemd 257.1" "sysupdate.features"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sysupdate.features \- Definition Files for Optional Features
.SH "SYNOPSIS"
.PP
.RS 4
/etc/sysupdate\&.d/*\&.feature
.RE
.RS 4
/run/sysupdate\&.d/*\&.feature
.RE
.RS 4
/usr/local/lib/sysupdate\&.d/*\&.feature
.RE
.RS 4
/usr/lib/sysupdate\&.d/*\&.feature
.RE
.SH "DESCRIPTION"
.PP
"Optional Features" are functionality provided by
\fBsystemd-sysupdate\fR(8), that allow a distribution to define sets of
\fBsysupdate.d\fR(5)
transfer definitions that are intended to be enabled or disabled by the system administrator\&.
.PP
When a feature is enabled, transfers belonging to it will be considered when checking for and downloading updates, when vacuuming, and in all other situations\&. In effect, transfers belonging to a feature will always be updated in lock\-step with the rest of their target\&. This is the primary difference an Optional Feature and a
\fBsystemd\-sysupdate\fR
component\&. When a feature is disabled, its transfers will not be considered when checking for and downloading updates, but
\fBsystemd\-sysupdate\fR
will still consider them while vacuuming and in other situations where it needs to determine ownership over previously downloaded system resources\&.
\fBsystemd\-sysupdate\fR
will clean up all instances of the feature\*(Aqs transfers whenever it is disabled, effectively uninstalling it\&.
.PP
Optional Features are described by
sysupdate\&.d/*\&.feature
files, which are defined below\&. Transfers can declare that they belong to a feature via the
\fIFeatures=\fR
setting\&. Feature definitions support drop\-in files, which are most commonly used to override the
\fIEnabled=\fR
setting)\&. They can also be masked out to hide the availability of the feature entirely\&.
.PP
Each
*\&.feature
file contains one section: [Feature]\&.
.SH "[FEATURE] SECTION OPTIONS"
.PP
This section defines general properties of this feature\&.
.PP
\fIDescription=\fR
.RS 4
A short human readable description of this feature\&. This may be used as a label for this feature, so the string should meaningfully identify the feature among the features available in
sysupdate\&.d/\&.
.sp
Added in version 257\&.
.RE
.PP
\fIDocumentation=\fR
.RS 4
A user\-presentable URL to documentation about this feature\&. This setting supports specifier expansion; see below for details on supported specifiers\&.
.sp
Added in version 257\&.
.RE
.PP
\fIAppStream=\fR
.RS 4
A URL to an
\m[blue]\fBAppStream catalog\fR\m[]\&\s-2\u[1]\d\s+2
XML file\&. This may be used by software centers (such as GNOME Software or KDE Discover) to present rich metadata about this feature\&. This includes display names, chagnelogs, icons, and more\&. This setting supports specifier expansion; see below for details on supported specifiers\&.
.sp
Added in version 257\&.
.RE
.PP
\fIEnabled=\fR
.RS 4
Whether or not this feature is enabled\&. If unspecified, the feature is disabled by default\&.
.sp
Added in version 257\&.
.RE
.SH "SPECIFIERS"
.PP
Specifiers may be used in the
\fIDocumentation=\fR
and
\fIAppStream=\fR
settings\&. The following expansions are understood:
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&Specifiers available
.TS
allbox tab(:);
lB lB lB.
T{
Specifier
T}:T{
Meaning
T}:T{
Details
T}
.T&
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l.
T{
"%a"
T}:T{
Architecture
T}:T{
A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&.
T}
T{
"%A"
T}:T{
Operating system image version
T}:T{
The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
T}
T{
"%b"
T}:T{
Boot ID
T}:T{
The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&.
T}
T{
"%B"
T}:T{
Operating system build ID
T}:T{
The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
T}
T{
"%H"
T}:T{
Host name
T}:T{
The hostname of the running system\&.
T}
T{
"%l"
T}:T{
Short host name
T}:T{
The hostname of the running system, truncated at the first dot to remove any domain component\&.
T}
T{
"%m"
T}:T{
Machine ID
T}:T{
The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&.
T}
T{
"%M"
T}:T{
Operating system image identifier
T}:T{
The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
T}
T{
"%o"
T}:T{
Operating system ID
T}:T{
The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&.
T}
T{
"%v"
T}:T{
Kernel release
T}:T{
Identical to \fBuname \-r\fR output\&.
T}
T{
"%w"
T}:T{
Operating system version ID
T}:T{
The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
T}
T{
"%W"
T}:T{
Operating system variant ID
T}:T{
The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
T}
T{
"%T"
T}:T{
Directory for temporary files
T}:T{
This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
T}
T{
"%V"
T}:T{
Directory for larger and persistent temporary files
T}:T{
This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
T}
T{
"%%"
T}:T{
Single percent sign
T}:T{
Use "%%" in place of "%" to specify a single percent sign\&.
T}
.TE
.sp 1
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Development Tools for Image\-Based OS\fR
.PP
We\*(Aqll use the hypothetical "foobarOS" described in
\fBsysupdate.d\fR(5)
as our example base OS\&. The vast majority of foobarOS\*(Aqs users have no need for a compiler, build system, debugger, and other such development tools to be part of their OS\&. However, the developers of foobarOS itself need this build tooling to be available\&. So, foobarOS needs to provide a system extension image (see
\fBsystemd-sysext\fR(8)) containing these development tools, and this image must be updated in lock\-step with the underlying base OS\&. This is a great use case for an optional OS feature, so let\*(Aqs define one:
.PP
.if n \{\
.RS 4
.\}
.nf
# /usr/lib/sysupdate\&.d/devel\&.feature
[Feature]
Description=Development Tools
Documentation=https://developer\&.example\&.com/foobarOS/getting\-started
Enabled=false
.fi
.if n \{\
.RE
.\}
.PP
The above defines the
"devel"
feature, and disables it by default\&. Now let\*(Aqs a define a transfer that\*(Aqs associated with this feature:
.PP
.if n \{\
.RS 4
.\}
.nf
# /usr/lib/sysupdate\&.d/50\-devel\&.transfer
[Transfer]
Features=devel
ProtectVersion=%A

[Source]
Type=url\-file
Path=https://download\&.example\&.com/
MatchPattern=foobarOS_@v_devel\&.raw\&.xz

[Target]
Type=regular\-file
Path=/var/lib/extensions
MatchPattern=foobarOS_@v_devel\&.raw
Mode=0444
InstancesMax=2
.fi
.if n \{\
.RE
.\}
.PP
With these two files, we have created a feature called
"devel"
that, when enabled, will download and decompress the appropriate version of
"https://download\&.example\&.com/foobarOS_@v_devel\&.raw\&.xz"
into
"/var/lib/extensions/foobarOS_@v_devel\&.raw"
during each OS update\&.
.PP
The developers of foobarOS can enable the
"devel"
feature on their workstations by creating the following drop\-in:
.PP
.if n \{\
.RS 4
.\}
.nf
# /etc/sysupdate\&.d/devel\&.feature\&.d/enable\&.conf
[Feature]
Enabled=true
.fi
.if n \{\
.RE
.\}

.PP
\fBExample\ \&2.\ \&Proprietary Drivers\fR
.PP
Suppose that many of foobarOS\*(Aqs users have a GPU manufactured by the MVISUAL corporation\&. Due to lack of documentation and difficulty in reverse\-engineering the hardware, the open\-source drivers for MVISUAL GPUs are unable to make proper use of available graphics and compute performance\&. MVISUAL provides a redistributable proprietary driver for their cards, and foobarOS\*(Aqs developers distribute them to address their users\*(Aq needs\&.
.PP
MVISUAL\*(Aqs driver has a couple different parts that must be installed for it to function: a UKI addon to configure the kernel command\-line, an initrd system extension image to add the MVISUAL kernel module into the initrd, and a regular system extension image to add the proprietary OpenGL and Vulkan userspace drivers\&. All of these should be version\-locked to the core OS\&.
.PP
Let\*(Aqs start by defining an optional feature named
"mvisual\-driver":
.PP
.if n \{\
.RS 4
.\}
.nf
# /usr/lib/sysupdate\&.d/mvisual\-driver\&.feature
[Feature]
Description=MVISUAL Proprietary GPU Driver
Documentation=https://support\&.example\&.com/foobarOS/mvisual
AppStream=https://metadata\&.example\&.com/mvisual\-driver\-%A\&.xml\&.gz
.fi
.if n \{\
.RE
.\}
.PP
Note that we define AppStream metadata for this feature, because we want software centers to present it to end\-users\&. Next, let\*(Aqs define the corresponding transfers:
.PP
.if n \{\
.RS 4
.\}
.nf
# /usr/lib/sysupdate\&.d/50\-mvisual\-userspace\&.transfer
[Transfer]
Features=mvisual\-driver
ProtectVersion=%A

[Source]
Type=url\-file
Path=https://download\&.example\&.com/
MatchPattern=foobarOS_@v_mvisual_userspace\&.raw\&.xz

[Target]
Type=regular\-file
Path=/var/lib/extensions
MatchPattern=foobarOS_@v_mvisual\&.raw
Mode=0444
InstancesMax=2
.fi
.if n \{\
.RE
.\}
.PP
.if n \{\
.RS 4
.\}
.nf
# /usr/lib/sysupdate\&.d/70\-mvisual\-initrd\&.transfer
[Transfer]
Features=mvisual\-driver
ProtectVersion=%A

[Source]
Type=url\-file
Path=https://download\&.example\&.com/
MatchPattern=foobarOS_@v_mvisual_initrd\&.raw\&.xz

[Target]
Type=regular\-file
Path=/EFI/Linux
PathRelativeTo=boot
MatchPattern=foobarOS_@v\&.efi\&.extra\&.d/foobarOS_mvisual\&.raw
Mode=0444
InstancesMax=2
.fi
.if n \{\
.RE
.\}
.PP
.if n \{\
.RS 4
.\}
.nf
# /usr/lib/sysupdate\&.d/90\-mvisual\-addon\&.transfer
[Transfer]
Features=mvisual\-driver
ProtectVersion=%A

[Source]
Type=url\-file
Path=https://download\&.example\&.com/
MatchPattern=foobarOS_@v_mvisual_addon\&.efi\&.xz

[Target]
Type=regular\-file
Path=/EFI/Linux
PathRelativeTo=boot
MatchPattern=foobarOS_@v\&.efi\&.extra\&.d/foobarOS_mvisual\&.addon\&.efi
Mode=0444
InstancesMax=2
.fi
.if n \{\
.RE
.\}

.PP
\fBExample\ \&3.\ \&Intersecting Features\fR
.PP
Suppose that MVISUAL releases special tooling to help a distribution developer troubleshoot crashes in their proprietary driver\&. Let\*(Aqs define a transfer:
.PP
.if n \{\
.RS 4
.\}
.nf
# /usr/lib/sysupdate\&.d/50\-mvisual\-debugger\&.transfer
[Transfer]
RequisiteFeatures=devel mvisual\-driver
ProtectVersion=%A

[Source]
Type=url\-file
Path=https://download\&.example\&.com/
MatchPattern=foobarOS_@v_devel\&.raw\&.xz

[Target]
Type=regular\-file
Path=/var/lib/extensions
MatchPattern=foobarOS_@v_devel\&.raw
Mode=0444
InstancesMax=2
.fi
.if n \{\
.RE
.\}
.PP
This transfer will be used only if both the
"devel"
and
"mvisual\-driver"
features are enabled\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsystemd-sysupdate\fR(8), \fBsysupdate.d\fR(5)
.SH "NOTES"
.IP " 1." 4
AppStream catalog
.RS 4
\%https://www.freedesktop.org/software/appstream/docs/chap-CatalogData.html
.RE