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