man/machine-info.xml

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