From 5ae4d543cb9b45ad6c6b82b78da1d6abc2291cdb Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Fri, 13 Jun 2014 19:45:52 +0200
Subject: os-release: define /usr/lib/os-release as fallback for
 /etc/os-release

The file should have been in /usr/lib/ in the first place, since it
describes the OS container in /usr (and not the configuration in /etc),
hence, let's support os-release files in /usr/lib as fallback if no
version in /etc exists, following the usual override logic.

A prior commit already enabled tmpfiles to create /etc/os-release as a
symlink to /usr/lib/os-release should it be missing, thus providing nice
compatibility with applications only checking in /etc.

While it's probably a good idea if all apps check both locations via a
fallback logic, it is only necessary in the early boot process, as long
as the /etc/os-release symlink has not been restored, in case we boot
with an empty /etc.
---
 man/os-release.xml | 38 +++++++++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 9 deletions(-)

(limited to 'man/os-release.xml')

diff --git a/man/os-release.xml b/man/os-release.xml
index c1dd62f715..11443638e5 100644
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -49,13 +49,15 @@
 
         <refsynopsisdiv>
                 <para><filename>/etc/os-release</filename></para>
+                <para><filename>/usr/lib/os-release</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
                 <title>Description</title>
 
-                <para>The <filename>/etc/os-release</filename> file
-                contains operating system identification data.</para>
+                <para>The <filename>/etc/os-release</filename> and
+                <filename>/usr/lib/os-release</filename> files contain
+                operating system identification data.</para>
 
                 <para>The basic file format of
                 <filename>os-release</filename> is a newline-separated
@@ -78,20 +80,38 @@
                 strings. Lines beginning with "#" shall be ignored as
                 comments.</para>
 
-                <para><filename>/etc/os-release</filename> contains
-                data that is defined by the operating system vendor
-                and should not be changed by the administrator.</para>
+                <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
+                <filename>/usr/lib/os-release</filename> if it is
+                missing. Applications should not read data from both
+                files at the same
+                time. <filename>/usr/lib/os-release</filename> is the
+                recommended place to store OS release information as
+                part of vendor trees. Frequently
+                <filename>/etc/os-release</filename> is simply a
+                symlink to <filename>/usr/lib/os-release</filename>,
+                to provide compatibility with applications only
+                looking at <filename>/etc</filename>.</para>
+
+                <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 file <filename>/etc/os-release</filename> might
-                be a symlink to another file, but it is important that
+                <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>
 
                 <para>For a longer rationale for
-                <filename>/etc/os-release</filename> please refer to
+                <filename>os-release</filename> please refer to
                 the <ulink
                 url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
         </refsect1>
@@ -100,7 +120,7 @@
                 <title>Options</title>
 
                 <para>The following OS identifications parameters may be set using
-                <filename>/etc/os-release</filename>:</para>
+                <filename>os-release</filename>:</para>
 
                 <variablelist>
 
-- 
cgit v1.2.3-54-g00ecf