mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-26 19:53:45 +08:00
Code Issues Packages Projects Releases Wiki Activity
main
systemd/man/os-release.xml

730 lines
39 KiB
XML
Raw Permalink Normal View History

man: document /etc/os-release
2010-11-22 03:05:51 +08:00
<?xml version='1.0'?> <!--*-nxml-*-->
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 21:40:58 +08:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 22:48:33 +08:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 12:23:58 +08:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: document /etc/os-release
2010-11-22 03:05:51 +08:00
man: add an example how to correctly read os-release in shell This is not entirely obvious. The logic of how to interpret the fields applies in any language, so drop the pointless mention of C or shell.
2021-05-21 01:47:55 +08:00
<refentry id="os-release" xmlns:xi="http://www.w3.org/2001/XInclude">
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<refentryinfo>
<title>os-release</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>os-release</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>os-release</refname>
man: say that initrd-release is like os-release
2021-05-21 17:11:01 +08:00
<refname>initrd-release</refname>
man: further document extension-release
2021-07-23 21:45:38 +08:00
<refname>extension-release</refname>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<refpurpose>Operating system identification</refpurpose>
</refnamediv>
<refsynopsisdiv>
man: use <simplelist> for file lists in synopsis With <para><filename>…</filename></para>, we get a separate "paragraph" for each line, i.e. entries separated by empty lines. This uses up a lot of space and was only done because docbook makes it hard to insert a newline. In some other places, <literallayout> was used, but then we cannot indent the source text (because the whitespace would end up in the final page). We can get the desired result with <simplelist>. With <simplelist> the items are indented in roff output, but not in html output. In some places this looks better then no indentation, and in others it would probably be better to have no indent. But this is a minor issue and we cannot control that. (I didn't convert all spots. There's a bunch of other man pages which have two lines, e.g. an executable and service file, and it doesn't matter there so much.)
2023-12-14 19:52:03 +08:00
<para><simplelist>
<member><filename>/etc/os-release</filename></member>
<member><filename>/usr/lib/os-release</filename></member>
<member><filename>/etc/initrd-release</filename></member>
<member><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></member>
</simplelist></para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>The <filename>/etc/os-release</filename> and
<filename>/usr/lib/os-release</filename> files contain operating
system identification data.</para>
man: refer to os-release(5) for description of files in the same format
2022-01-07 23:38:18 +08:00
<para>The format of <filename>os-release</filename> is a newline-separated list of
man: extend os-release docs a bit regarding quotes Fixes: #21194
2021-11-09 01:19:43 +08:00
environment-like shell-compatible variable assignments. It is possible to source the configuration from
Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this
means variable expansion is explicitly not supported), allowing applications to read the file without
implementing a shell compatible execution engine. Variable assignment values must be enclosed in double
or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z,
0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is
optional.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes,
following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not
man: refer to os-release(5) for description of files in the same format
2022-01-07 23:38:18 +08:00
be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#"
are treated as comments. Blank lines are permitted and ignored.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<para>The file <filename>/etc/os-release</filename> takes
precedence over <filename>/usr/lib/os-release</filename>.
Applications should check for the former, and exclusively use its
data if it exists, and only fall back to
man: reword some sentences with umbiguous subjects A sencence like "The system manager does, a, b, c, which is really d, and e.", it is generally understood that the manager also does "e". This can be quite confusing if the manager cannot do "e", in our case unmount the file system on which it is sitting. Similary, we cannot "fall back to x if it is missing", since "it" in that sentence means "x".
2024-09-23 17:45:25 +08:00
<filename>/usr/lib/os-release</filename> if that is missing.
Applications should not combine the data from both files.
<filename>/usr/lib/os-release</filename> is the recommended
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
place to store OS release information as part of vendor trees.
<filename>/etc/os-release</filename> should be a relative symlink
to <filename>/usr/lib/os-release</filename>, to provide
compatibility with applications only looking at
man: use trailing slash on directories in more places
2020-10-06 00:08:21 +08:00
<filename>/etc/</filename>. A relative symlink instead of an
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
absolute symlink is necessary to avoid breaking the link in a
Remove a few references to dracut Let's remove some explicit references to dracut as we prefer initrds built with mkosi these days.
2024-01-19 21:21:24 +08:00
chroot or initrd environment.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<para><filename>os-release</filename> contains data that is
defined by the operating system vendor and should generally not be
changed by the administrator.</para>
<para>As this file only encodes names and identifiers it should
not be localized.</para>
<para>The <filename>/etc/os-release</filename> and
<filename>/usr/lib/os-release</filename> files might be symlinks
to other files, but it is important that the file is available
from earliest boot on, and hence must be located on the root file
system.</para>
man/os-release: add a note about repeating entries We didn't actually say that keys should not be repeated. At least the examples in docs (both python and shell) would do that, and any simple parser that builds a dictionary would most likely behave the same way. But let's document this expectation, but also say how to deal with malformed files.
2022-03-08 17:10:12 +08:00
<para><filename>os-release</filename> must not contain repeating keys. Nevertheless, readers should pick
the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A
reader may warn about repeating entries.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<para>For a longer rationale for <filename>os-release</filename>
please refer to the <ulink
tree-wide: use https for the 0pointer.de doc links
2023-06-23 19:08:57 +08:00
url="https://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
man: say that initrd-release is like os-release
2021-05-21 17:11:01 +08:00
<refsect2>
<title><filename>/etc/initrd-release</filename></title>
man: slightly enhance docs about "exitrd" and remove TODO entry for it The concept is fairly well established and present in our docs in various places. Say that the exitrd is also marked by the presence of /etc/initrd-release.
2024-09-23 17:41:29 +08:00
<para>In the <ulink url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink>
and exitrd,
man: say that initrd-release is like os-release
2021-05-21 17:11:01 +08:00
<filename>/etc/initrd-release</filename> plays the same role as <filename>os-release</filename> in the
man: slightly enhance docs about "exitrd" and remove TODO entry for it The concept is fairly well established and present in our docs in various places. Say that the exitrd is also marked by the presence of /etc/initrd-release.
2024-09-23 17:41:29 +08:00
main system. Additionally, the presence of that file means that the system is in the initrd/exitrd phase.
man: say that initrd-release is like os-release
2021-05-21 17:11:01 +08:00
<filename>/etc/os-release</filename> should be symlinked to <filename>/etc/initrd-release</filename>
(or vice versa), so programs that only look for <filename>/etc/os-release</filename> (as described
man: adjust the description of extension-release.*
2021-08-21 22:02:09 +08:00
above) work correctly.</para>
<para>The rest of this document that talks about <filename>os-release</filename> should be understood
to apply to <filename>initrd-release</filename> too.</para>
man: say that initrd-release is like os-release
2021-05-21 17:11:01 +08:00
</refsect2>
man: further document extension-release
2021-07-23 21:45:38 +08:00
<refsect2>
<title><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></title>
<para><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>
man: adjust the description of extension-release.*
2021-08-21 22:02:09 +08:00
plays the same role for extension images as <filename>os-release</filename> for the main system, and
follows the syntax and rules as described in the <ulink
man: "Documentation" is not part of the title <ulinks> contents are used to generate a SEE ALSO section at the bottom of a man page, so we need to include the title, without additional words, in the content.
2023-11-06 22:00:46 +08:00
url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> page. The purpose of this
man: adjust the description of extension-release.*
2021-08-21 22:02:09 +08:00
file is to identify the extension and to allow the operating system to verify that the extension image
matches the base OS. This is typically implemented by checking that the <varname>ID=</varname> options
match, and either <varname>SYSEXT_LEVEL=</varname> exists and matches too, or if it is not present,
<varname>VERSION_ID=</varname> exists and matches. This ensures ABI/API compatibility between the
layers and prevents merging of an incompatible image in an overlay.</para>
os-release: add 'SYSEXT_' fields for version/id sysext DDI cannot carry an os-release file, but have to carry an extension-release file. But so far, this was only used to match the sysext DDI with the base DDI/rootdir. It is also useful to describe the sysext DDI itself, just like we do in os-release. So document that the same fields used in os-release can also be added to an extension-release, with the 'SYSEXT_' prefix, and in that case they are understood to define the sysext DDI itself, rather than for matching purposes.
2023-03-24 23:10:11 +08:00
<para>In order to identify the extension image itself, the same fields defined below can be added to the
<filename>extension-release</filename> file with a <varname>SYSEXT_</varname> prefix (to disambiguate
from fields used to match on the base image). E.g.: <varname>SYSEXT_ID=myext</varname>,
<varname>SYSEXT_VERSION_ID=1.2.3</varname>.</para>
man: adjust the description of extension-release.*
2021-08-21 22:02:09 +08:00
<para>In the <filename>extension-release.<replaceable>IMAGE</replaceable></filename> filename, the
<replaceable>IMAGE</replaceable> part must exactly match the file name of the containing image with the
suffix removed. In case it is not possible to guarantee that an image file name is stable and doesn't
change between the build and the deployment phases, it is possible to relax this check: if exactly one
file whose name matches <literal><filename>extension-release.*</filename></literal> is present in this
directory, and the file is tagged with a <varname>user.extension-release.strict</varname>
Fix man page links Based on linkchecker as usual.
2022-04-12 17:02:16 +08:00
<citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry> set to the
man: adjust the description of extension-release.*
2021-08-21 22:02:09 +08:00
string <literal>0</literal>, it will be used instead.</para>
<para>The rest of this document that talks about <filename>os-release</filename> should be understood
to apply to <filename>extension-release</filename> too.</para>
man: further document extension-release
2021-07-23 21:45:38 +08:00
</refsect2>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsect1>
<refsect1>
<title>Options</title>
<para>The following OS identifications parameters may be set using
<filename>os-release</filename>:</para>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
<refsect2>
<title>General information identifying the operating system</title>
<variablelist class='environment-variables'>
<varlistentry>
<term><varname>NAME=</varname></term>
<listitem><para>A string identifying the operating system, without a version component, and
suitable for presentation to the user. If not set, a default of <literal>NAME=Linux</literal> may
be used.</para>
<para>Examples: <literal>NAME=Fedora</literal>, <literal>NAME="Debian GNU/Linux"</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ID=</varname></term>
<listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
and "-") identifying the operating system, excluding any version information and suitable for
processing by scripts or usage in generated filenames. If not set, a default of
man: extend os-release docs a bit regarding quotes Fixes: #21194
2021-11-09 01:19:43 +08:00
<literal>ID=linux</literal> may be used. Note that even though this string may not include
characters that require shell quoting, quoting may nevertheless be used.</para>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
<para>Examples: <literal>ID=fedora</literal>, <literal>ID=debian</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ID_LIKE=</varname></term>
<listitem><para>A space-separated list of operating system identifiers in the same syntax as the
<varname>ID=</varname> setting. It should list identifiers of operating systems that are closely
related to the local operating system in regards to packaging and programming interfaces, for
example listing one or more OS identifiers the local OS is a derivative from. An OS should
generally only list other OS identifiers it itself is a derivative of, and not any OSes that are
derived from it, though symmetric relationships are possible. Build scripts and similar should
check this variable if they need to identify the local operating system and the value of
<varname>ID=</varname> is not recognized. Operating systems should be listed in order of how
closely the local operating system relates to the listed ones, starting with the closest. This
field is optional.</para>
<para>Examples: for an operating system with <literal>ID=centos</literal>, an assignment of
<literal>ID_LIKE="rhel fedora"</literal> would be appropriate. For an operating system with
<literal>ID=ubuntu</literal>, an assignment of <literal>ID_LIKE=debian</literal> is appropriate.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PRETTY_NAME=</varname></term>
<listitem><para>A pretty operating system name in a format suitable for presentation to the
user. May or may not contain a release code name or OS version of some kind, as suitable. If not
set, a default of <literal>PRETTY_NAME="Linux"</literal> may be used</para>
<para>Example: <literal>PRETTY_NAME="Fedora 17 (Beefy Miracle)"</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>CPE_NAME=</varname></term>
<listitem><para>A CPE name for the operating system, in URI binding syntax, following the <ulink
url="http://scap.nist.gov/specifications/cpe/">Common Platform Enumeration Specification</ulink> as
proposed by the NIST. This field is optional.</para>
<para>Example: <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal></para></listitem>
</varlistentry>
<varlistentry>
<term><varname>VARIANT=</varname></term>
<listitem><para>A string identifying a specific variant or edition of the operating system suitable
for presentation to the user. This field may be used to inform the user that the configuration of
this system is subject to a specific divergent set of rules or default configuration settings. This
field is optional and may not be implemented on all systems.</para>
<para>Examples: <literal>VARIANT="Server Edition"</literal>, <literal>VARIANT="Smart Refrigerator
Edition"</literal>.</para>
<para>Note: this field is for display purposes only. The <varname>VARIANT_ID</varname> field should
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 23:03:38 +08:00
be used for making programmatic decisions.</para>
<xi:include href="version-info.xml" xpointer="v220"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
<varlistentry>
<term><varname>VARIANT_ID=</varname></term>
<listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and
"-"), identifying a specific variant or edition of the operating system. This may be interpreted by
other packages in order to determine a divergent default configuration. This field is optional and
may not be implemented on all systems.</para>
<para>Examples: <literal>VARIANT_ID=server</literal>, <literal>VARIANT_ID=embedded</literal>.
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 23:03:38 +08:00
</para>
<xi:include href="version-info.xml" xpointer="v220"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Information about the version of the operating system</title>
<variablelist class='environment-variables'>
<varlistentry>
<term><varname>VERSION=</varname></term>
<listitem><para>A string identifying the operating system version, excluding any OS name
information, possibly including a release code name, and suitable for presentation to the
user. This field is optional.</para>
<para>Examples: <literal>VERSION=17</literal>, <literal>VERSION="17 (Beefy Miracle)"</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>VERSION_ID=</varname></term>
<listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information
or release code name, and suitable for processing by scripts or usage in generated filenames. This
field is optional.</para>
<para>Examples: <literal>VERSION_ID=17</literal>, <literal>VERSION_ID=11.04</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>VERSION_CODENAME=</varname></term>
<listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
and "-") identifying the operating system release code name, excluding any OS name information or
release version, and suitable for processing by scripts or usage in generated filenames. This field
is optional and may not be implemented on all systems.</para>
<para>Examples: <literal>VERSION_CODENAME=buster</literal>,
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 23:03:38 +08:00
<literal>VERSION_CODENAME=xenial</literal>.</para>
<xi:include href="version-info.xml" xpointer="v231"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
<varlistentry>
<term><varname>BUILD_ID=</varname></term>
man: reword description of BUILD_ID in os-release Our description was pretty hard to parse. Let's replace it with a description loosely based on a fairly clear description written by a distro that actually uses BUILD_ID: https://developer.rigado.com/docsets/Working-with-the-Rigado-Vesta-Gateway/latest/production/versioning-images.html#the-rigos-scheme.
2021-05-21 02:37:55 +08:00
<listitem><para>A string uniquely identifying the system image originally used as the installation
base. In most cases, <varname>VERSION_ID</varname> or
<varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> are updated when the entire system
image is replaced during an update. <varname>BUILD_ID</varname> may be used in distributions where
the original installation image version is important: <varname>VERSION_ID</varname> would change
during incremental system updates, but <varname>BUILD_ID</varname> would not. This field is
optional.</para>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
<para>Examples: <literal>BUILD_ID="2013-03-20.3"</literal>, <literal>BUILD_ID=201303203</literal>.
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 23:03:38 +08:00
</para>
<xi:include href="version-info.xml" xpointer="v200"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
<varlistentry>
<term><varname>IMAGE_ID=</varname></term>
<listitem><para> A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
and "-"), identifying a specific image of the operating system. This is supposed to be used for
environments where OS images are prepared, built, shipped and updated as comprehensive, consistent
OS images. This field is optional and may not be implemented on all systems, in particularly not on
those that are not managed via images but put together and updated from individual packages and on
the local system.</para>
<para>Examples: <literal>IMAGE_ID=vendorx-cashier-system</literal>,
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<literal>IMAGE_ID=netbook-image</literal>.</para>
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
<varlistentry>
<term><varname>IMAGE_VERSION=</varname></term>
<listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with
<varname>IMAGE_ID</varname> described above, to discern different versions of the same image.
</para>
<para>Examples: <literal>IMAGE_VERSION=33</literal>, <literal>IMAGE_VERSION=47.1rc1</literal>.
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
</para>
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
os-release: Add RELEASE_TYPE= This will allow GUIs to customize their behavior a little based on the type of release. For example, an OS installer may display a warning/disclaimer if RELEASE_TYPE=prerelease. The software updates app might be a bit more insistent about upgrading to the next major release if RELEASE_TYPE=stable than if RELEASE_TYPE=lts
2024-05-23 06:06:54 +08:00
<varlistentry>
<term><varname>RELEASE_TYPE=</varname></term>
<listitem><para>A lower-case string (no spaces or other characters outside of 0-9, a-z, ".",
"_", and "-"), describing what kind of release this version of the OS is. Known values follow:
os-release: break RELEASE_TYPE into paragraphs and clarify about rolling stable releases Arch and Tumbleweed do not do EOLs but are still stable, so clarify the paragraph. Also break the entry in paragraphs, to make it more readable when rendered.
2024-08-02 03:44:11 +08:00
</para>
<itemizedlist>
<listitem><para><literal>stable</literal> is for normal releases of the system, suitable for
production use. Generally, stable releases become end-of-life soon after the next major stable
release is out, although this might not be the case if, for example, a distribution adopts a
rolling release model and still be production ready. Examples include Fedora 40, Ubuntu 23.10,
OpenSUSE Tumbleweed, and Arch Linux.</para></listitem>
<listitem><para><literal>lts</literal> is for long term support releases of the system, suitable
for production use and supported for an extended period of time. Generally, LTS releases
man: fix typo Follow-up for 7102dc52e6b03248da1f01b3a8a4b83c6d7a1316 and 3d689b675b565c29a51c7127ae30839987aaa18b.
2024-08-03 04:46:28 +08:00
continue to receive support even if newer major releases of the distribution are available.
os-release: break RELEASE_TYPE into paragraphs and clarify about rolling stable releases Arch and Tumbleweed do not do EOLs but are still stable, so clarify the paragraph. Also break the entry in paragraphs, to make it more readable when rendered.
2024-08-02 03:44:11 +08:00
Examples include Ubuntu 24.04, Debian 12 Bookworm and RHEL 9.4.</para></listitem>
<listitem><para><literal>development</literal> is for unstable versions of the system,
unsuitable for production use, such as alpha, beta, or rolling unstable releases. Examples
include Fedora Rawhide, Debian Testing, Fedora 40 Beta, and GNOME OS Nightly.</para></listitem>
<listitem><para><literal>experiment</literal> is for experimental builds of the system, created
specifically to test some work-in-progress feature. This is meant to be used in combination with
<varname>EXPERIMENT=</varname>.</para></listitem>
</itemizedlist>
<para>If unset, or an unknown value, assume that the release is <literal>stable</literal>.</para>
os-release: Add RELEASE_TYPE= This will allow GUIs to customize their behavior a little based on the type of release. For example, an OS installer may display a warning/disclaimer if RELEASE_TYPE=prerelease. The software updates app might be a bit more insistent about upgrading to the next major release if RELEASE_TYPE=stable than if RELEASE_TYPE=lts
2024-05-23 06:06:54 +08:00
os-release: change RELEASE_TYPE value from 'pre-release' to 'development' The point was made on https://lists.debian.org/debian-ctte/2024/08/msg00005.html that 'pre-release sounds' like an RC candidate, ie, something that will change very slightly in the released version. But this is not necessarily the case for example at the beginnig of a Fedora Rawhide or Debian Testing release cycle, so change it to a more generic 'development' Follow-up for 7102dc52e6b03248da1f01b3a8a4b83c6d7a1316
2024-08-02 03:35:57 +08:00
<para>Examples: <literal>RELEASE_TYPE=development</literal>, <literal>RELEASE_TYPE=lts</literal>.
os-release: Add RELEASE_TYPE= This will allow GUIs to customize their behavior a little based on the type of release. For example, an OS installer may display a warning/disclaimer if RELEASE_TYPE=prerelease. The software updates app might be a bit more insistent about upgrading to the next major release if RELEASE_TYPE=stable than if RELEASE_TYPE=lts
2024-05-23 06:06:54 +08:00
</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</variablelist>
man: reword description of BUILD_ID in os-release Our description was pretty hard to parse. Let's replace it with a description loosely based on a fairly clear description written by a distro that actually uses BUILD_ID: https://developer.rigado.com/docsets/Working-with-the-Rigado-Vesta-Gateway/latest/production/versioning-images.html#the-rigos-scheme.
2021-05-21 02:37:55 +08:00
<para>To summarize: if the image updates are built and shipped as comprehensive units,
<varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> is the best fit. Otherwise, if updates
eventually completely replace previously installed contents, as in a typical binary distribution,
<varname>VERSION_ID</varname> should be used to identify major releases of the operating system.
<varname>BUILD_ID</varname> may be used instead or in addition to <varname>VERSION_ID</varname> when
the original system image version is important.</para>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</refsect2>
<refsect2>
<title>Presentation information and links</title>
<variablelist class='environment-variables'>
<varlistentry>
<term><varname>HOME_URL=</varname></term>
<term><varname>DOCUMENTATION_URL=</varname></term>
<term><varname>SUPPORT_URL=</varname></term>
<term><varname>BUG_REPORT_URL=</varname></term>
<term><varname>PRIVACY_POLICY_URL=</varname></term>
<listitem><para>Links to resources on the Internet related to the operating system.
<varname>HOME_URL=</varname> should refer to the homepage of the operating system, or alternatively
some homepage of the specific version of the operating system.
<varname>DOCUMENTATION_URL=</varname> should refer to the main documentation page for this
operating system. <varname>SUPPORT_URL=</varname> should refer to the main support page for the
operating system, if there is any. This is primarily intended for operating systems which vendors
provide support for. <varname>BUG_REPORT_URL=</varname> should refer to the main bug reporting page
for the operating system, if there is any. This is primarily intended for operating systems that
rely on community QA. <varname>PRIVACY_POLICY_URL=</varname> should refer to the main privacy
policy page for the operating system, if there is any. These settings are optional, and providing
only some of these settings is common. These URLs are intended to be exposed in "About this system"
UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a
Bug", or "Privacy Policy". The values should be in <ulink
url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be
<literal>http:</literal> or <literal>https:</literal> URLs, and possibly <literal>mailto:</literal>
or <literal>tel:</literal>. Only one URL shall be listed in each setting. If multiple resources
need to be referenced, it is recommended to provide an online landing page linking all available
resources.</para>
<para>Examples: <literal>HOME_URL="https://fedoraproject.org/"</literal>,
<literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal>.</para></listitem>
</varlistentry>
os-release: define SUPPORT_END= Fixes #21764. I think is very simple, but flexible. The date may be set early, for distros that have a fixed schedule, but it doesn't have to. So for example Debian could push out an update that sets a few months before the release goes EOL. And various tools, in particular graphical desktops, can start nagging people to upgrade a few weeks before the date. As discussed in the bug, we don't need granularity higher than a day. And this means that we can use a simple human- and machine-readable format. I was considering other names, e.g. something with "EOL", but I think that "SUPPORT_END" is better because it doesn't imply that the machine will somehow stop working. This is supposed to be an advisory, nothing more.
2022-07-06 23:19:27 +08:00
<varlistentry>
<term><varname>SUPPORT_END=</varname></term>
<listitem><para>The date at which support for this version of the OS ends. (What exactly "lack of
support" means varies between vendors, but generally users should assume that updates, including
man: redefine SUPPORT_END= to mean one day earlier I thought it would be nice to specify the last day of support, because I thought it'd seem more natural. But in practice this doesn't work well, because such a truncated timestamp is usually taken to mean midnight that starts the given date. I.e. 2011-12-13 is a shorthand for 2011-12-13 00:00:00 and not 2011-12-13 23:59:59.999999999999. Let's instead specify that the given date is the first unsupported day, which is meaningful for humans, and let the computer treat it as midnight, which gives consistent interpratation.
2022-07-09 23:50:36 +08:00
security fixes, will not be provided.) The value is a date in the ISO 8601 format
<literal>YYYY-MM-DD</literal>, and specifies the first day on which support <emphasis>is
not</emphasis> provided.</para>
<para>For example, <literal>SUPPORT_END=2001-01-01</literal> means that the system was supported
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
until the end of the last day of the previous millennium.</para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
os-release: define SUPPORT_END= Fixes #21764. I think is very simple, but flexible. The date may be set early, for distros that have a fixed schedule, but it doesn't have to. So for example Debian could push out an update that sets a few months before the release goes EOL. And various tools, in particular graphical desktops, can start nagging people to upgrade a few weeks before the date. As discussed in the bug, we don't need granularity higher than a day. And this means that we can use a simple human- and machine-readable format. I was considering other names, e.g. something with "EOL", but I think that "SUPPORT_END" is better because it doesn't imply that the machine will somehow stop working. This is supposed to be an advisory, nothing more.
2022-07-06 23:19:27 +08:00
</varlistentry>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
<varlistentry>
<term><varname>LOGO=</varname></term>
<listitem><para>A string, specifying the name of an icon as defined by <ulink
Use https for freedesktop.org grep -l -r http:// | xargs sed -E -i s'#http://(.*).freedesktop.org#https://\1.freedesktop.org#'
2022-06-28 18:00:47 +08:00
url="https://standards.freedesktop.org/icon-theme-spec/latest">freedesktop.org Icon Theme
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
Specification</ulink>. This can be used by graphical applications to display an operating system's
or distributor's logo. This field is optional and may not necessarily be implemented on all
systems.</para>
<para>Examples: <literal>LOGO=fedora-logo</literal>, <literal>LOGO=distributor-logo-opensuse</literal>
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 23:03:38 +08:00
</para>
<xi:include href="version-info.xml" xpointer="v240"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
<varlistentry>
<term><varname>ANSI_COLOR=</varname></term>
<listitem><para>A suggested presentation color when showing the OS name on the console. This should
be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting
graphical rendition. This field is optional.</para>
<para>Examples: <literal>ANSI_COLOR="0;31"</literal> for red, <literal>ANSI_COLOR="1;34"</literal>
for light blue, or <literal>ANSI_COLOR="0;38;2;60;110;180"</literal> for Fedora blue.
</para></listitem>
</varlistentry>
man/os-release: Add VENDOR_NAME= and VENDOR_URL= keys to os-release These will be used in UIs to refer to the company or organization which produces the OS separately from referring to the OS itself. Signed-off-by: Philip Withnall <pwithnall@endlessos.org> Fixes: #27777
2023-05-31 22:49:42 +08:00
<varlistentry>
<term><varname>VENDOR_NAME=</varname></term>
<listitem><para>The name of the OS vendor. This is the name of the organization or company which
produces the OS. This field is optional.</para>
<para>This name is intended to be exposed in "About this system" UIs or software update UIs when
needed to distinguish the OS vendor from the OS itself. It is intended to be human readable.</para>
<para>Examples: <literal>VENDOR_NAME="Fedora Project"</literal> for Fedora Linux,
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<literal>VENDOR_NAME="Canonical"</literal> for Ubuntu.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
man/os-release: Add VENDOR_NAME= and VENDOR_URL= keys to os-release These will be used in UIs to refer to the company or organization which produces the OS separately from referring to the OS itself. Signed-off-by: Philip Withnall <pwithnall@endlessos.org> Fixes: #27777
2023-05-31 22:49:42 +08:00
</varlistentry>
<varlistentry>
<term><varname>VENDOR_URL=</varname></term>
<listitem><para>The homepage of the OS vendor. This field is optional. The
<varname>VENDOR_NAME=</varname> field should be set if this one is, although clients must be
robust against either field not being set.</para>
<para>The value should be in <ulink
url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be
<literal>http:</literal> or <literal>https:</literal> URLs. Only one URL shall be listed in the
setting.</para>
<para>Examples: <literal>VENDOR_URL="https://fedoraproject.org/"</literal>,
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<literal>VENDOR_URL="https://canonical.com/"</literal>.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
man/os-release: Add VENDOR_NAME= and VENDOR_URL= keys to os-release These will be used in UIs to refer to the company or organization which produces the OS separately from referring to the OS itself. Signed-off-by: Philip Withnall <pwithnall@endlessos.org> Fixes: #27777
2023-05-31 22:49:42 +08:00
</varlistentry>
os-release: Introduce experiment RELEASE_TYPE This is for experimental builds of the OS made to test some specific WIP feature. For example, let's say the distro in question is Asahi Linux and Apple just released the M3 SoC. The Asahi developers will start porting to the M3, and will quickly generate builds of Asahi Linux that can technically boot but aren't ready for any kind of daily use. These images are marked as experimental, and can be shared among the developers. If a user somehow stumbles upon one of these images and tries to install it, they'll be warned that they're about to install an experimental Apple M3 port of Asahi Linux. Eventually, once the Asahi developers think that their M3 port is ready for a wider audience, they can merge it into the mainline Asahi repos, where it will be distributed through the usual nightly CI builds (where RELEASE_TYPE=pre-release; M3 support is no longer experimental).
2024-05-24 11:39:52 +08:00
<varlistentry>
<term><varname>EXPERIMENT=</varname></term>
<listitem><para>A human-presentable description of what makes this build of the OS experimental.
This field is optional. The <varname>RELEASE_TYPE</varname> field should be set to <literal>experiment</literal>
if this field is set, otherwise clients should ignore this field.</para>
<para>This description is intended to be exposed at system installation time, or in "About this system" UIs,
to warn the user that they're installing/running an experimental build of the OS. If <varname>RELEASE_TYPE</varname>
is <literal>experiment</literal> but this field is unset, the UI should still warn the user, but it
will be unable to explain what exactly is experimental about the current build of the OS.</para>
<para>Examples: <literal>EXPERIMENT="Switch to DNF5"</literal> for an experimental build of Fedora
Linux made to test DNF5, <literal>EXPERIMENT="Port to Apple M3 chip"</literal> for experimental
builds of Asahi Linux ported to the Apple M3 SoC,
<literal>EXPERIMENT="Mutter !1441: Dynamic triple/double buffering (v4)"</literal> for builds of GNOME
OS created by Mutter's CI for merge request !1441.</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>EXPERIMENT_URL=</varname></term>
<listitem><para>The main informational page about what makes the current OS build experimental, where users
can learn more about the experiment's status and potentially leave feedback. This field is optional. The
<varname>EXPERIMENT=</varname> field should be set if this one is, although clients must be robust against
either field not being set.</para>
<para>The value should be in <ulink
url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be
<literal>http:</literal> or <literal>https:</literal> URLs. Only one URL shall be listed in the
setting.</para>
<para>Examples, corresponding to the examples above in <varname>EXPERIMENT=</varname>:
<literal>EXPERIMENT_URL="https://fedoraproject.org/wiki/Changes/SwitchToDnf5"</literal>,
<literal>EXPERIMENT_URL="https://github.com/AsahiLinux/docs/wiki/M3-Series-Feature-Support"</literal>,
<literal>EXPERIMENT_URL="https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1441"</literal>.</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</variablelist>
</refsect2>
<refsect2>
<title>Distribution-level defaults and metadata</title>
<variablelist class='environment-variables'>
<varlistentry>
<term><varname>DEFAULT_HOSTNAME=</varname></term>
<listitem><para>A string specifying the hostname if
<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> is not
present and no other configuration source specifies the hostname. Must be either a single DNS label
(a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the
format allowed for DNS domain name labels), or a sequence of such labels separated by single dots
that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux
limitation (DNS allows longer names).</para>
<para>See <citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for a description of how
<citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 23:03:38 +08:00
determines the fallback hostname.</para>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
sysext: introduce ARCHITECTURE field to match host architecture When an extension image has binaries they should match the host architecture. Currently there is no way to specify this requirement. Introduce an ARCHITECTURE field in the extension's release file that may be set to prevent loading on the wrong host architecture. Since this new field is introduced late, we don't want to make specifying it mandatory as it would break existing sysext images. See https://github.com/systemd/systemd/issues/24061
2022-08-09 23:07:20 +08:00
<varlistentry>
<term><varname>ARCHITECTURE=</varname></term>
<listitem><para>A string that specifies which CPU architecture the userspace binaries require.
The architecture identifiers are the same as for <varname>ConditionArchitecture=</varname>
described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
The field is optional and should only be used when just single architecture is supported.
It may provide redundant information when used in a GPT partition with a GUID type that already
encodes the architecture. If this is not the case, the architecture should be specified in
e.g., an extension image, to prevent an incompatible host from loading it.
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
</para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
sysext: introduce ARCHITECTURE field to match host architecture When an extension image has binaries they should match the host architecture. Currently there is no way to specify this requirement. Introduce an ARCHITECTURE field in the extension's release file that may be set to prevent loading on the wrong host architecture. Since this new field is introduced late, we don't want to make specifying it mandatory as it would break existing sysext images. See https://github.com/systemd/systemd/issues/24061
2022-08-09 23:07:20 +08:00
</varlistentry>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
<varlistentry>
<term><varname>SYSEXT_LEVEL=</varname></term>
<listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which
man: further document extension-release
2021-07-23 21:45:38 +08:00
extension images are supported. See <filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>,
tree-wide: link to docs.kernel.org for kernel documentation https://www.kernel.org/ links to https://docs.kernel.org/ for the documentation. See https://git.kernel.org/pub/scm/docs/kernel/website.git/commit/?id=ebc1c372850f249dd143c6d942e66c88ec610520 These URLs are shorter and nicer looking.
2022-07-04 22:26:30 +08:00
<ulink url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink> and
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
<citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
for more information.</para>
<para>Examples: <literal>SYSEXT_LEVEL=2</literal>, <literal>SYSEXT_LEVEL=15.14</literal>.
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 23:03:38 +08:00
</para>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</varlistentry>
extension-release.d/: add a new field SYSEXT_SCOPE= for clarifying what a system extension is for This should make things a bit more robust since it ensures system extension can only applied to the right environments. Right now three different "scopes" are defined: 1. "system" (for regular OS systems, after the initrd transition) 2. "initrd" (for sysext images that apply to the initrd environment) 3. "portable" (for sysext images that apply to portable images) If not specified we imply a default of "system portable", i.e. any image where the field is not specified is implicitly OK for application to OS images and for portable services – but not for initrds.
2021-11-19 05:00:31 +08:00
confext: documentation and man page updates for confext
2023-02-24 16:42:45 +08:00
<varlistentry>
<term><varname>CONFEXT_LEVEL=</varname></term>
<listitem><para>Semantically the same as <varname>SYSEXT_LEVEL=</varname> but for confext images.
See <filename>/etc/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>
for more information.</para>
<para>Examples: <literal>CONFEXT_LEVEL=2</literal>, <literal>CONFEXT_LEVEL=15.14</literal>.
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
confext: documentation and man page updates for confext
2023-02-24 16:42:45 +08:00
</varlistentry>
extension-release.d/: add a new field SYSEXT_SCOPE= for clarifying what a system extension is for This should make things a bit more robust since it ensures system extension can only applied to the right environments. Right now three different "scopes" are defined: 1. "system" (for regular OS systems, after the initrd transition) 2. "initrd" (for sysext images that apply to the initrd environment) 3. "portable" (for sysext images that apply to portable images) If not specified we imply a default of "system portable", i.e. any image where the field is not specified is implicitly OK for application to OS images and for portable services – but not for initrds.
2021-11-19 05:00:31 +08:00
<varlistentry>
<term><varname>SYSEXT_SCOPE=</varname></term>
<listitem><para>Takes a space-separated list of one or more of the strings
<literal>system</literal>, <literal>initrd</literal> and <literal>portable</literal>. This field is
only supported in <filename>extension-release.d/</filename> files and indicates what environments
man: say that SYSEXT_SCOPE=initrd also applies to exitrds We generally do _not_ want the same sysexts to be loaded in both initrd and exitrd phases. The environment is completely different and it's unlikely that the same code can be useful in both places. Nevertheless, it can be useful in _some_ cases, for example when the sysexts contains debugging tools. I think we don't need to differentiate between initrds and exitrds through SYSEXT_SCOPE, because the two types are made available in completely different locations and loaded through a different mechanism, with very little chance of an initrd being loaded as an exitrd without an explicit admin action (or the other way around). So let's not complicate our code or definitions by an explicit "exitrd" sysext designator, but just clarify that "initrd" also encompasses exitrds in this context.
2024-09-23 18:01:21 +08:00
the system extension is applicable to: i.e. to regular systems, to initrds and exitrds, or to
portable service images. If not specified, <literal>SYSEXT_SCOPE=system portable</literal> is
implied, i.e. any system extension without this field is applicable to regular systems and to
portable service environments, but not to initrd/exitrd environments.</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
extension-release.d/: add a new field SYSEXT_SCOPE= for clarifying what a system extension is for This should make things a bit more robust since it ensures system extension can only applied to the right environments. Right now three different "scopes" are defined: 1. "system" (for regular OS systems, after the initrd transition) 2. "initrd" (for sysext images that apply to the initrd environment) 3. "portable" (for sysext images that apply to portable images) If not specified we imply a default of "system portable", i.e. any image where the field is not specified is implicitly OK for application to OS images and for portable services – but not for initrds.
2021-11-19 05:00:31 +08:00
</varlistentry>
os-release: add new PORTABLE_PREFIXES= field for declaring valid portable service match prefixes
2021-11-19 23:19:19 +08:00
confext: documentation and man page updates for confext
2023-02-24 16:42:45 +08:00
<varlistentry>
<term><varname>CONFEXT_SCOPE=</varname></term>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<listitem><para>Semantically the same as <varname>SYSEXT_SCOPE=</varname> but for confext images.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
confext: documentation and man page updates for confext
2023-02-24 16:42:45 +08:00
</varlistentry>
os-release: add new PORTABLE_PREFIXES= field for declaring valid portable service match prefixes
2021-11-19 23:19:19 +08:00
<varlistentry>
<term><varname>PORTABLE_PREFIXES=</varname></term>
<listitem><para>Takes a space-separated list of one or more valid prefix match strings for the
man: "Documentation" is not part of the title <ulinks> contents are used to generate a SEE ALSO section at the bottom of a man page, so we need to include the title, without additional words, in the content.
2023-11-06 22:00:46 +08:00
<ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> logic.
man: fix issues reported by the manpage-l10n project Fixes #25780. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=> > > "Force LUKS mode\\&. When this mode is used, the following options are " > "ignored since they are provided by the LUKS header on the device: " > "I<cipher=>, I<hash=>, I<size=>" Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=> > > "Use TrueCrypt encryption mode\\&. When this mode is used, the following " > "options are ignored since they are provided by the TrueCrypt header on the " > "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-" > "size=>, I<size=>" Same. > Man page: journalctl.1 > Issue 1: make be → may be Fixed. > Issue 2: below\\&. → below: Fixed. > Man page: journalctl.1 > Issue: Colon at the end? > > "The following commands are understood\\&. If none is specified the default " > "is to display journal records\\&." > msgstr "" > "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist " > "die Anzeige von Journal-Datensätzen die Vorgabe\\&." This is a bit awkward, but I'm not sure how to fix it. > Man page: kernel-install.8 > Issue: methods a fallback → methods fallback It was correct, but I added a comma to make the sense clearer. > Man page: loader.conf.5 > Issue 1: secure boot variables → Secure Boot variables > Issue 2: one → one for (multiple times) > > "Supported secure boot variables are one database for authorized images, one " > "key exchange key (KEK) and one platform key (PK)\\&. For more information, " > "refer to the \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, " > "under Secure Boot and Driver Signing\\&. Another resource that describe the " > "interplay of the different variables is the \\m[blue]B<EDK2 " > "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&." "one of" would sound strange. "One this and one that" is OK. > Man page: loader.conf.5 > Issue: systemd-boot → B<systemd-boot>(7) Fixed. > Man page: logind.conf.5 > Issue: systemd-logind → B<systemd-logind>(8) We use <filename>systemd-logind</> on subsequent references… I think that's good enough. > Man page: nss-myhostname.8 > Issue: B<getent> → B<getent>(1) Fixed. > Man page: nss-resolve.8 > Issue: B<systemd-resolved> → B<systemd-resolved>(8) The first reference does this, subsequent are shorter. > Man page: os-release.5 > Issue: Portable Services → Portable Services Documentation? Updated. > Man page: pam_systemd_home.8 > Issue: auth and account use "reason", while session and password do not? Reworded. > Man page: portablectl.1 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: repart.d.5 > Issue: The partition → the partition Fixed. > Man page: repart.d.5 > Issue: B<systemd-repart> → B<systemd-repart>(8) The first reference does this. I also change this one, because it's pretty far down in the text. > Man page: systemd.1 > Issue: kernel command line twice? > > "Takes a boolean argument\\&. If false disables importing credentials from " > "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&." Apparently this was fixed already. > Man page: systemd-boot.7 > Issue: enrollement → enrollment Fixed. > Man page: systemd-cryptenroll.1 > Issue: multiple cases: any specified → the specified Reworded. > Man page: systemd-cryptenroll.1 > Issue: If this this → If this Fixed tree-wide. > Man page: systemd-cryptsetup-generator.8 > Issue: and the initrd → and in the initrd "Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file. > Man page: systemd.directives.7 > Issue: Why are these two quoted (but not others)? > > "B<\\*(Aqh\\*(Aq>" > > B<\\*(Aqs\\*(Aq>" > > "B<\\*(Aqy\\*(Aq>" This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this. > Man page: systemd.exec.5 > Issue 1: B<at>(1p) → B<at>(1) > Issue 2: B<crontab>(1p) → B<crontab>(1) Fixed. > Man page: systemd.exec.5 > Issue: B<select()> → B<select>(2) Fixed. > Man page: systemd.exec.5 > Issue: qemu → B<qemu>(1) The man page doesn't seem to be in any of the canonical places on the web. I added a link to online docs. > Man page: systemd.exec.5 > Issue: variable → variables Seems to be fixed already. > Man page: systemd-integritysetup-generator.8 > Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator> I changed <filename> to <command>. > Man page: systemd-integritysetup-generator.8 > Issue: superfluous comma at the end Already fixed. > Man page: systemd-measure.1 > Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below) Reworded. > Man page: systemd-measure.1 > Issue: =PATH> → =>I<PATH> Fixed. > Man page: systemd-measure.1.po > Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST> Fixed. > Man page: systemd.netdev.5 > Issue: os the → on the Appears to have been fixed already. > Man page: systemd.netdev.5 > Issue: Onboard → On-board (as in previous string) Updated. > Man page: systemd.network.5 > Issue: B<systemd-networkd> -> B<systemd-networkd>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: B<netlabelctl> → B<netlabelctl>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a " I dropped the comma. > Man page: systemd-nspawn.1 > Issue: All host users outside of that range → All other host users Reworded. > # FIXME no effect → no effect\\&. > #. type: Plain text > #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed > msgid "" > "Whichever ID mapping option is used, the same mapping will be used for users " > "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind " > "mounted directory will have no effect" A period is added. Not sure if there's some other issue. > Man page: systemd-oomd.service.8 > Issue: B<systemd> → B<systemd>(1) Done. > Man page: systemd.path.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd-pcrphase.service.8 > Issue 1: indicate phases into TPM2 PCR 11 ?? > Issue 2: Colon at the end of the paragraph? Fixed. > Man page: systemd-pcrphase.service.8 > Issue: final boot phase → final shutdown phase? Updated. > Man page: systemd-pcrphase.service.8 > Issue: for the the → for the Fixed tree-wide. > Man page: systemd-portabled.service.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd-pstore.service.8 > Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot). > > "and we look up \"localhost\", nss-dns will send the following queries to " > "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", " > "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the " > "first two queries fail, systemd-resolved will synthesize an answer for the " > "third query." Looks all OK to me. > Man page: systemd.resource-control.5 > Issue: Missing closing bracket after link to Control Groups version 1 Fixed. > Man page: systemd-sysext.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd.timer.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd.unit.5 > Issue: that is → that are Fixed. > Man page: systemd-veritysetup-generator.8 > Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator> > > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&." > > "systemd-veritysetup-generator understands the following kernel command line " > "parameters:" Updated. > Man page: systemd-volatile-root.service.8 > Issue: initrdyes → Initrd Fixed. > Man page: sysupdate.d.5 > Issue: : → \\&. (As above in TRANSFER) Updated. > Man page: sysupdate.d.5 > Issue: some → certain Updated. > Man page: sysupdate.d.5 > Issue 1: i\\&.e\\& → I\\&.e\\& Fixed. > Issue 2: the image → the system "image" seems correct. > Man page: tmpfiles.d.5 > Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8) Updated.
2023-01-11 23:45:59 +08:00
This field serves two purposes: it is informational, identifying portable service images as such
(and thus allowing them to be distinguished from other OS images, such as bootable system images).
It is also used when a portable service image is attached: the specified or implied portable
service prefix is checked against the list specified here, to enforce restrictions how images may
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
be attached to a system.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
os-release: add new PORTABLE_PREFIXES= field for declaring valid portable service match prefixes
2021-11-19 23:19:19 +08:00
</varlistentry>
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
</variablelist>
</refsect2>
<refsect2>
<title>Notes</title>
man: add an example how to correctly read os-release in shell This is not entirely obvious. The logic of how to interpret the fields applies in any language, so drop the pointless mention of C or shell.
2021-05-21 01:47:55 +08:00
<para>If you are using this file to determine the OS or a specific version of it, use the
<varname>ID</varname> and <varname>VERSION_ID</varname> fields, possibly with
man: reorder fields in os-release Let's order the fields from the most general to least: os name, os variant, os version, machine-parseable version details, metadata, special settings. I added section headers to roughly group the settings. The division is not strict, because for example CPE_NAME also includes the version, and PRETTY_NAME may too, but it still makes it easier to find the right name. Also split out Examples to separate paragraphs: almost all descriptions had "Example:" at the end, where multiple examples were listed. Splitting this out to separate paragraphs makes the whole thing much easier to read. Add missing markup and punctuation while at it. About - If not set, defaults to <literal>NAME=Linux</literal>. + If not set, a default of <literal>NAME=Linux</literal> may be used. and similar changes: in many circumstances, if this is not set, no value should be used. The fallback mostly make sense when we need to present something to the user. So let's reword this to not imply that the default is necessary.
2021-05-20 20:57:06 +08:00
<varname>ID_LIKE</varname> as fallback for <varname>ID</varname>. When looking for an OS identification
string for presentation to the user use the <varname>PRETTY_NAME</varname> field.</para>
<para>Note that operating system vendors may choose not to provide version information, for example to
accommodate for rolling releases. In this case, <varname>VERSION</varname> and
<varname>VERSION_ID</varname> may be unset. Applications should not rely on these fields to be
set.</para>
<para>Operating system vendors may extend the file format and introduce new fields. It is highly
recommended to prefix new fields with an OS specific name in order to avoid name clashes. Applications
reading this file must ignore unknown fields.</para>
<para>Example: <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal>.</para>
<para>Container and sandbox runtime managers may make the host's identification data available to
applications by providing the host's <filename>/etc/os-release</filename> (if available, otherwise
<filename>/usr/lib/os-release</filename> as a fallback) as
<filename>/run/host/os-release</filename>.</para>
</refsect2>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsect1>
<refsect1>
man: add an example how to correctly read os-release in shell This is not entirely obvious. The logic of how to interpret the fields applies in any language, so drop the pointless mention of C or shell.
2021-05-21 01:47:55 +08:00
<title>Examples</title>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
man: add an example how to correctly read os-release in shell This is not entirely obvious. The logic of how to interpret the fields applies in any language, so drop the pointless mention of C or shell.
2021-05-21 01:47:55 +08:00
<example>
<title><filename>os-release</filename> file for Fedora Workstation</title>
<programlisting>NAME=Fedora
man: update os-release(5) to use 24bit ANSI color in example Given that ANSI_COLOR= is mostly about branding it probably makes sense to use RGB rather than paletted colors for them, so that the colors match the project design as close as possible. Hence, provide a 25bit RGB example for ANSI_COLOR, and update the overall example to something newer. Also see: https://bugzilla.redhat.com/show_bug.cgi?id=1823099
2020-04-13 15:20:25 +08:00
VERSION="32 (Workstation Edition)"
man: document /etc/os-release
2010-11-22 03:05:51 +08:00
ID=fedora
man: update os-release(5) to use 24bit ANSI color in example Given that ANSI_COLOR= is mostly about branding it probably makes sense to use RGB rather than paletted colors for them, so that the colors match the project design as close as possible. Hence, provide a 25bit RGB example for ANSI_COLOR, and update the overall example to something newer. Also see: https://bugzilla.redhat.com/show_bug.cgi?id=1823099
2020-04-13 15:20:25 +08:00
VERSION_ID=32
PRETTY_NAME="Fedora 32 (Workstation Edition)"
ANSI_COLOR="0;38;2;60;110;180"
LOGO=fedora-logo-icon
CPE_NAME="cpe:/o:fedoraproject:fedora:32"
man: add URL field definitions to os-release(5) As requested by Raphaël Hertzog from the Debian project, include information about the home page and support/bug report pages in /etc/os-release.
2012-03-07 00:44:32 +08:00
HOME_URL="https://fedoraproject.org/"
man: update os-release(5) to use 24bit ANSI color in example Given that ANSI_COLOR= is mostly about branding it probably makes sense to use RGB rather than paletted colors for them, so that the colors match the project design as close as possible. Hence, provide a 25bit RGB example for ANSI_COLOR, and update the overall example to something newer. Also see: https://bugzilla.redhat.com/show_bug.cgi?id=1823099
2020-04-13 15:20:25 +08:00
DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
BUG_REPORT_URL="https://bugzilla.redhat.com/"
REDHAT_BUGZILLA_PRODUCT="Fedora"
REDHAT_BUGZILLA_PRODUCT_VERSION=32
REDHAT_SUPPORT_PRODUCT="Fedora"
REDHAT_SUPPORT_PRODUCT_VERSION=32
PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
VARIANT="Workstation Edition"
VARIANT_ID=workstation</programlisting>
man: add an example how to correctly read os-release in shell This is not entirely obvious. The logic of how to interpret the fields applies in any language, so drop the pointless mention of C or shell.
2021-05-21 01:47:55 +08:00
</example>
man: further document extension-release
2021-07-23 21:45:38 +08:00
<example>
<title><filename>extension-release</filename> file for an extension for Fedora Workstation 32</title>
<programlisting>ID=fedora
VERSION_ID=32</programlisting>
</example>
man: add an example how to correctly read os-release in shell This is not entirely obvious. The logic of how to interpret the fields applies in any language, so drop the pointless mention of C or shell.
2021-05-21 01:47:55 +08:00
<example>
<title>Reading <filename>os-release</filename> in
Fix man page links Based on linkchecker as usual.
2022-04-12 17:02:16 +08:00
<citerefentry project='man-pages'><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
man: add an example how to correctly read os-release in shell This is not entirely obvious. The logic of how to interpret the fields applies in any language, so drop the pointless mention of C or shell.
2021-05-21 01:47:55 +08:00
<programlisting><xi:include href="check-os-release.sh" parse="text" /></programlisting>
</example>
man: add example os-release mangling in python This is also not entirely obvious. I think the code I came up with is pretty elegant ;] The final part of of the code that makes use of the parsed data is kept very similar to the shell code on purpose, even though it could be written a bit more idiomatically.
2021-05-21 02:00:18 +08:00
<example>
<title>Reading <filename>os-release</filename> in
Fix man page links Based on linkchecker as usual.
2022-04-12 17:02:16 +08:00
<citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions &gt;= 3.10)</title>
man: recommend built-in platform.freedesktop_os_release() in our page Python gained support for reading os-release, let's advertise it a bit more. Our open-coded example is still useful, but let's not suggest it as the default implementation. I added quotes around the printed string because it looks a bit better this way.
2022-02-28 16:47:28 +08:00
<programlisting><xi:include href="check-os-release-simple.py" parse="text" /></programlisting>
<para>See docs for <ulink url="https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release">
<function>platform.freedesktop_os_release</function></ulink> for more details.
</para>
</example>
<example>
<title>Reading <filename>os-release</filename> in
Fix man page links Based on linkchecker as usual.
2022-04-12 17:02:16 +08:00
<citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version)</title>
man: add example os-release mangling in python This is also not entirely obvious. I think the code I came up with is pretty elegant ;] The final part of of the code that makes use of the parsed data is kept very similar to the shell code on purpose, even though it could be written a bit more idiomatically.
2021-05-21 02:00:18 +08:00
<programlisting><xi:include href="check-os-release.py" parse="text" /></programlisting>
man: recommend built-in platform.freedesktop_os_release() in our page Python gained support for reading os-release, let's advertise it a bit more. Our open-coded example is still useful, but let's not suggest it as the default implementation. I added quotes around the printed string because it looks a bit better this way.
2022-02-28 16:47:28 +08:00
<para>Note that the above version that uses the built-in implementation is preferred
in most cases, and the open-coded version here is provided for reference.</para>
man: add example os-release mangling in python This is also not entirely obvious. I think the code I came up with is pretty elegant ;] The final part of of the code that makes use of the parsed data is kept very similar to the shell code on purpose, even though it could be written a bit more idiomatically.
2021-05-21 02:00:18 +08:00
</example>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsect1>
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-23 02:09:32 +08:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='die-net'><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
</simplelist></para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsect1>
man: document /etc/os-release
2010-11-22 03:05:51 +08:00
</refentry>
Reference in New Issue Copy Permalink