man/nss-myhostname.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="nss-myhostname" conditional='ENABLE_NSS_MYHOSTNAME'>
   7
   8   <refentryinfo>
   9     <title>nss-myhostname</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>nss-myhostname</refentrytitle>
  15     <manvolnum>8</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>nss-myhostname</refname>
  20     <refname>libnss_myhostname.so.2</refname>
  21     <refpurpose>Hostname resolution for the locally configured system hostname</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><filename>libnss_myhostname.so.2</filename></para>
  26   </refsynopsisdiv>
  27
  28   <refsect1>
  29     <title>Description</title>
  30
  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>
  36
  37     <itemizedlist>
  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>
  43
  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>
  48
  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>
  54     </itemizedlist>
  55
  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>
  65
  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>
  68
  69     <para>It is recommended to place <literal>myhostname</literal> either between <literal>resolve</literal>
  70     and "traditional" modules like <literal>files</literal> and <literal>dns</literal>, or after them. In the
  71     first version, well-known names like <literal>localhost</literal> and the machine hostname are given
  72     higher priority than the external configuration. This is recommended when the external DNS servers and
  73     network are not absolutely trusted. In the second version, external configuration is given higher
  74     priority and <command>nss-myhostname</command> only provides a fallback mechanism. This might be suitable
  75     in closely controlled networks, for example on a company LAN.</para>
  76   </refsect1>
  77
  78   <refsect1>
  79     <title>Example</title>
  80
  81     <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
  82     <command>nss-myhostname</command> correctly:</para>
  83
  84     <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
  85 <programlisting>passwd:         compat systemd
  86 group:          compat systemd
  87 shadow:         compat
  88
  89 # Either (untrusted network):
  90 hosts:          mymachines resolve [!UNAVAIL=return] <command>myhostname</command> files dns
  91 # Or (only trusted networks):
  92 hosts:          mymachines resolve [!UNAVAIL=return] files dns <command>myhostname</command>
  93 networks:       files
  94
  95 protocols:      db files
  96 services:       db files
  97 ethers:         db files
  98 rpc:            db files
  99
 100 netgroup:       nis</programlisting>
 101
 102     <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
 103
 104     <programlisting>$ getent ahosts `hostname`
 105 ::1       STREAM omega
 106 ::1       DGRAM
 107 ::1       RAW
 108 127.0.0.2       STREAM
 109 127.0.0.2       DGRAM
 110 127.0.0.2       RAW</programlisting>
 111
 112     <para>In this case, the local hostname is <varname>omega</varname>.</para>
 113
 114   </refsect1>
 115
 116   <refsect1>
 117     <title>See Also</title>
 118     <para>
 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>
 125     </para>
 126   </refsect1>
 127
 128 </refentry>