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