man/machine-info.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="machine-info" xmlns:xi="http://www.w3.org/2001/XInclude">
   7   <refentryinfo>
   8     <title>machine-info</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>machine-info</refentrytitle>
  14     <manvolnum>5</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>machine-info</refname>
  19     <refpurpose>Local machine information file</refpurpose>
  20   </refnamediv>
  21
  22   <refsynopsisdiv>
  23     <para><filename>/etc/machine-info</filename></para>
  24   </refsynopsisdiv>
  25
  26   <refsect1>
  27     <title>Description</title>
  28
  29     <para>The <filename>/etc/machine-info</filename> file contains
  30     machine metadata.</para>
  31
  32     <para>The format of <filename>machine-info</filename> is a newline-separated list of environment-like
  33     shell-compatible variable assignments, ignoring comments and empty lines. It is possible to source the
  34     configuration from shell scripts, however, beyond mere variable assignments no shell features are
  35     supported, allowing applications to read the file without implementing a shell compatible execution
  36     engine. See
  37     <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
  38     detailed description of the format.</para>
  39
  40     <para><filename>/etc/machine-info</filename> contains metadata about the machine that is set by the user
  41     or administrator. The settings configured here have the highest precedence. When not set, appropriate
  42     values may be determined automatically, based on the information about the hardware or other
  43     configuration files. It is thus completely fine for this file to not be present.</para>
  44
  45     <para>You may use
  46     <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  47     to change the settings of this file from the command line.</para>
  48   </refsect1>
  49
  50   <refsect1>
  51     <title>Options</title>
  52
  53     <para>The following machine metadata parameters may be set using
  54     <filename>/etc/machine-info</filename>:</para>
  55
  56     <variablelist class='environment-variables'>
  57
  58       <varlistentry>
  59         <term><varname>PRETTY_HOSTNAME=</varname></term>
  60
  61         <listitem><para>A pretty human-readable UTF-8 machine
  62         identifier string. This should contain a name like
  63         <literal>Lennart's Laptop</literal> which is useful to present
  64         to the user and does not suffer by the syntax limitations of
  65         internet domain names. If possible, the internet hostname as
  66         configured in <filename>/etc/hostname</filename> should be
  67         kept similar to this one. Example: if this value is
  68         <literal>Lennart's Computer</literal> an Internet hostname of
  69         <literal>lennarts-computer</literal> might be a good choice.
  70         If this parameter is not set, an application should fall back
  71         to the Internet hostname for presentation
  72         purposes.</para></listitem>
  73       </varlistentry>
  74
  75       <varlistentry>
  76         <term><varname>ICON_NAME=</varname></term>
  77
  78         <listitem><para>An icon identifying this machine according to
  79         the <ulink
  80         url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
  81         Icon Naming Specification</ulink>. If this parameter is not
  82         set, an application should fall back to
  83         <literal>computer</literal> or a similar icon
  84         name.</para></listitem>
  85       </varlistentry>
  86
  87       <varlistentry>
  88         <term><varname>CHASSIS=</varname></term>
  89
  90         <listitem><para>The chassis type. Currently, the following
  91         chassis types are defined:
  92         <literal>desktop</literal>,
  93         <literal>laptop</literal>,
  94         <literal>convertible</literal>,
  95         <literal>server</literal>,
  96         <literal>tablet</literal>,
  97         <literal>handset</literal>,
  98         <literal>watch</literal>, and
  99         <literal>embedded</literal>,
 100         as well as the special chassis types
 101         <literal>vm</literal> and
 102         <literal>container</literal> for
 103         virtualized systems that lack an immediate physical chassis.</para>
 104
 105         <para>Note that most systems allow detection of the chassis type automatically (based on firmware
 106         information or suchlike). This setting should only be used to override a misdetection or to manually
 107         configure the chassis type where automatic detection is not available.</para>
 108
 109         <xi:include href="version-info.xml" xpointer="v197"/></listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term><varname>DEPLOYMENT=</varname></term>
 114
 115         <listitem><para>Describes the system deployment environment.
 116         One of the following is suggested:
 117         <literal>development</literal>,
 118         <literal>integration</literal>,
 119         <literal>staging</literal>,
 120         <literal>production</literal>.
 121         </para>
 122
 123         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><varname>LOCATION=</varname></term>
 128
 129         <listitem><para>Describes the system location if applicable
 130         and known. Takes a human-friendly, free-form string. This may
 131         be as generic as <literal>Berlin, Germany</literal> or as
 132         specific as <literal>Left Rack, 2nd Shelf</literal>.
 133         </para>
 134
 135         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term><varname>HARDWARE_VENDOR=</varname></term>
 140
 141         <listitem><para>Specifies the hardware vendor. If unspecified, the hardware vendor set in DMI or
 142         <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> will be
 143         used.</para>
 144
 145         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 146       </varlistentry>
 147
 148       <varlistentry>
 149         <term><varname>HARDWARE_MODEL=</varname></term>
 150
 151         <listitem><para>Specifies the hardware model. If unspecified, the hardware model set in DMI or
 152         <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> will be
 153         used.</para>
 154
 155         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 156       </varlistentry>
 157     </variablelist>
 158   </refsect1>
 159
 160   <refsect1>
 161     <title>Example</title>
 162
 163     <programlisting>PRETTY_HOSTNAME="Lennart's Tablet"
 164 ICON_NAME=computer-tablet
 165 CHASSIS=tablet
 166 DEPLOYMENT=production</programlisting>
 167   </refsect1>
 168
 169   <refsect1>
 170       <title>See Also</title>
 171       <para><simplelist type="inline">
 172         <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 173         <member><citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 174         <member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 175         <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 176         <member><citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 177         <member><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 178       </simplelist></para>
 179   </refsect1>
 180
 181 </refentry>