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+ -->
6 <refentry id=
"nss-myhostname" conditional='ENABLE_NSS_MYHOSTNAME'
>
9 <title>nss-myhostname
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>nss-myhostname
</refentrytitle>
15 <manvolnum>8</manvolnum>
19 <refname>nss-myhostname
</refname>
20 <refname>libnss_myhostname.so
.2</refname>
21 <refpurpose>Hostname resolution for the locally configured system hostname
</refpurpose>
25 <para><filename>libnss_myhostname.so
.2</filename></para>
29 <title>Description
</title>
31 <para><command>nss-myhostname
</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of
32 the GNU C Library (
<command>glibc
</command>), primarily providing hostname resolution for the locally configured
33 system hostname as returned by
34 <citerefentry><refentrytitle>gethostname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>. The precise
35 hostnames resolved by this module are:
</para>
38 <listitem><para>The local, configured hostname is resolved to
39 all locally configured IP addresses ordered by their scope, or
40 — if none are configured — the IPv4 address
127.0.0.2 (which
41 is on the local loopback) and the IPv6 address ::
1 (which is the
42 local host).
</para></listitem>
44 <listitem><para>The hostnames
<literal>localhost
</literal> and
45 <literal>localhost.localdomain
</literal> (as well as any hostname
46 ending in
<literal>.localhost
</literal> or
<literal>.localhost.localdomain
</literal>)
47 are resolved to the IP addresses
127.0.0.1 and ::
1.
</para></listitem>
49 <listitem><para>The hostname
<literal>_gateway
</literal> is
50 resolved to all current default routing gateway addresses,
51 ordered by their metric. This assigns a stable hostname to the
52 current gateway, useful for referencing it independently of the
53 current network configuration state.
</para></listitem>
56 <para>Various software relies on an always-resolvable local
57 hostname. When using dynamic hostnames, this is traditionally
58 achieved by patching
<filename>/etc/hosts
</filename> at the same
59 time as changing the hostname. This is problematic since it
60 requires a writable
<filename>/etc
</filename> file system and is
61 fragile because the file might be edited by the administrator at
62 the same time. With
<command>nss-myhostname
</command> enabled,
63 changing
<filename>/etc/hosts
</filename> is unnecessary, and on
64 many systems, the file becomes entirely optional.
</para>
66 <para>To activate the NSS modules, add
<literal>myhostname
</literal> to the line starting with
67 <literal>hosts:
</literal> in
<filename>/etc/nsswitch.conf
</filename>.
</para>
69 <para>It is recommended to place
<literal>myhostname
</literal> either between
<literal>resolve
</literal>
70 and
"traditional" modules like
<literal>dns
</literal>, or after them. In the first version, well-known
71 names like
<literal>localhost
</literal> and the machine hostname are given higher priority than the
72 external configuration. This is recommended when the external DNS servers and network are not absolutely
73 trusted. In the second version, external configuration is given higher priority and
74 <command>nss-myhostname
</command> only provides a fallback mechanism. This might be suitable in closely
75 controlled networks, for example on a company LAN.
</para>
79 <title>Example
</title>
81 <para>Here is an example
<filename>/etc/nsswitch.conf
</filename> file that enables
82 <command>nss-myhostname
</command> correctly:
</para>
84 <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
85 <programlisting>passwd: compat systemd
86 group: compat [SUCCESS=merge] systemd
89 # Either (untrusted network, see above):
90 hosts: mymachines resolve [!UNAVAIL=return] files
<command>myhostname
</command> dns
91 # Or (only trusted networks):
92 hosts: mymachines resolve [!UNAVAIL=return] files dns
<command>myhostname
</command>
100 netgroup: nis
</programlisting>
102 <para>To test, use
<command>glibc
</command>'s
<command>getent
</command> tool:
</para>
104 <programlisting>$ getent ahosts `hostname`
110 127.0.0.2 RAW
</programlisting>
112 <para>In this case, the local hostname is
<varname>omega
</varname>.
</para>
117 <title>See Also
</title>
119 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
120 <citerefentry><refentrytitle>nss-systemd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
121 <citerefentry><refentrytitle>nss-resolve
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
122 <citerefentry><refentrytitle>nss-mymachines
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
123 <citerefentry project='man-pages'
><refentrytitle>nsswitch.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
124 <citerefentry project='man-pages'
><refentrytitle>getent
</refentrytitle><manvolnum>1</manvolnum></citerefentry>