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