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