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