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