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+ -->
   5
   6 <refentry id="machine-info">
   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 basic file format of <filename>machine-info</filename>
  33     is a newline-separated list of environment-like shell-compatible
  34     variable assignments. It is possible to source the configuration
  35     from shell scripts, however, beyond mere variable assignments no
  36     shell features are supported, allowing applications to read the
  37     file without implementing a shell compatible execution
  38     engine.</para>
  39
  40     <para><filename>/etc/machine-info</filename> contains metadata
  41     about the machine that is set by the user or administrator.</para>
  42
  43     <para>Depending on the operating system other configuration files
  44     might be checked for machine information as well, however only as
  45     fallback.</para>
  46
  47     <para>You may use
  48     <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  49     to change the settings of this file from the command line.</para>
  50   </refsect1>
  51
  52   <refsect1>
  53     <title>Options</title>
  54
  55     <para>The following machine metadata parameters may be set using
  56     <filename>/etc/machine-info</filename>:</para>
  57
  58     <variablelist class='environment-variables'>
  59
  60       <varlistentry>
  61         <term><varname>PRETTY_HOSTNAME=</varname></term>
  62
  63         <listitem><para>A pretty human-readable UTF-8 machine
  64         identifier string. This should contain a name like
  65         <literal>Lennart's Laptop</literal> which is useful to present
  66         to the user and does not suffer by the syntax limitations of
  67         internet domain names. If possible, the internet hostname as
  68         configured in <filename>/etc/hostname</filename> should be
  69         kept similar to this one. Example: if this value is
  70         <literal>Lennart's Computer</literal> an Internet hostname of
  71         <literal>lennarts-computer</literal> might be a good choice.
  72         If this parameter is not set, an application should fall back
  73         to the Internet hostname for presentation
  74         purposes.</para></listitem>
  75       </varlistentry>
  76
  77       <varlistentry>
  78         <term><varname>ICON_NAME=</varname></term>
  79
  80         <listitem><para>An icon identifying this machine according to
  81         the <ulink
  82         url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
  83         Icon Naming Specification</ulink>. If this parameter is not
  84         set, an application should fall back to
  85         <literal>computer</literal> or a similar icon
  86         name.</para></listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term><varname>CHASSIS=</varname></term>
  91
  92         <listitem><para>The chassis type. Currently, the following
  93         chassis types are defined:
  94         <literal>desktop</literal>,
  95         <literal>laptop</literal>,
  96         <literal>convertible</literal>,
  97         <literal>server</literal>,
  98         <literal>tablet</literal>,
  99         <literal>handset</literal>,
 100         <literal>watch</literal>, and
 101         <literal>embedded</literal>,
 102         as well as the special chassis types
 103         <literal>vm</literal> and
 104         <literal>container</literal> for
 105         virtualized systems that lack an immediate physical chassis.
 106         Note that many systems allow detection of the chassis type
 107         automatically (based on firmware information or suchlike).
 108         This setting (if set) shall take precedence over automatically
 109         detected information and is useful to override misdetected
 110         configuration or to manually configure the chassis type where
 111         automatic detection is not available.</para></listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><varname>DEPLOYMENT=</varname></term>
 116
 117         <listitem><para>Describes the system deployment environment.
 118         One of the following is suggested:
 119         <literal>development</literal>,
 120         <literal>integration</literal>,
 121         <literal>staging</literal>,
 122         <literal>production</literal>.
 123         </para></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></listitem>
 134       </varlistentry>
 135     </variablelist>
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>Example</title>
 140
 141     <programlisting>PRETTY_HOSTNAME="Lennart's Tablet"
 142 ICON_NAME=computer-tablet
 143 CHASSIS=tablet
 144 DEPLOYMENT=production</programlisting>
 145   </refsect1>
 146
 147   <refsect1>
 148       <title>See Also</title>
 149       <para>
 150         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 151         <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 152         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 153         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 154         <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 155         <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 156       </para>
 157   </refsect1>
 158
 159 </refentry>