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>Provide hostname resolution for the locally
  22     configured system hostname.</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <para><filename>libnss_myhostname.so.2</filename></para>
  27   </refsynopsisdiv>
  28
  29   <refsect1>
  30     <title>Description</title>
  31
  32     <para><command>nss-myhostname</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of
  33     the GNU C Library (<command>glibc</command>), primarily providing hostname resolution for the locally configured
  34     system hostname as returned by
  35     <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.  The precise
  36     hostnames resolved by this module are:</para>
  37
  38     <itemizedlist>
  39       <listitem><para>The local, configured hostname is resolved to
  40       all locally configured IP addresses ordered by their scope, or
  41       — if none are configured — the IPv4 address 127.0.0.2 (which
  42       is on the local loopback) and the IPv6 address ::1 (which is the
  43       local host).</para></listitem>
  44
  45       <listitem><para>The hostnames <literal>localhost</literal> and
  46       <literal>localhost.localdomain</literal> (as well as any hostname
  47       ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>)
  48       are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem>
  49
  50       <listitem><para>The hostname <literal>_gateway</literal> is
  51       resolved to all current default routing gateway addresses,
  52       ordered by their metric. This assigns a stable hostname to the
  53       current gateway, useful for referencing it independently of the
  54       current network configuration state.</para></listitem>
  55     </itemizedlist>
  56
  57     <para>Various software relies on an always-resolvable local
  58     hostname. When using dynamic hostnames, this is traditionally
  59     achieved by patching <filename>/etc/hosts</filename> at the same
  60     time as changing the hostname. This is problematic since it
  61     requires a writable <filename>/etc</filename> file system and is
  62     fragile because the file might be edited by the administrator at
  63     the same time. With <command>nss-myhostname</command> enabled,
  64     changing <filename>/etc/hosts</filename> is unnecessary, and on
  65     many systems, the file becomes entirely optional.</para>
  66
  67     <para>To activate the NSS modules, add <literal>myhostname</literal> to the line starting with
  68     <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para>
  69
  70     <para>It is recommended to place <literal>myhostname</literal> either between <literal>resolve</literal>
  71     and "traditional" modules like <literal>files</literal> and <literal>dns</literal>, or after them. In the
  72     first version, well-known names like <literal>localhost</literal> and the machine hostname are given
  73     higher priority than the external configuration. This is recommended when the external DNS servers and
  74     network are not absolutely trusted. In the second version, external configuration is given higher
  75     priority and <command>nss-myhostname</command> only provides a fallback mechanism. This might be suitable
  76     in closely controlled networks, for example on a company LAN.</para>
  77   </refsect1>
  78
  79   <refsect1>
  80     <title>Example</title>
  81
  82     <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
  83     <command>nss-myhostname</command> correctly:</para>
  84
  85     <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
  86 <programlisting>passwd:         compat mymachines systemd
  87 group:          compat mymachines systemd
  88 shadow:         compat
  89
  90 # Either (untrusted network):
  91 hosts:          mymachines resolve [!UNAVAIL=return] <command>myhostname</command> files dns
  92 # Or (only trusted networks):
  93 hosts:          mymachines resolve [!UNAVAIL=return] files dns <command>myhostname</command>
  94 networks:       files
  95
  96 protocols:      db files
  97 services:       db files
  98 ethers:         db files
  99 rpc:            db files
 100
 101 netgroup:       nis</programlisting>
 102
 103     <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
 104
 105     <programlisting>$ getent ahosts `hostname`
 106 ::1       STREAM omega
 107 ::1       DGRAM
 108 ::1       RAW
 109 127.0.0.2       STREAM
 110 127.0.0.2       DGRAM
 111 127.0.0.2       RAW</programlisting>
 112
 113     <para>In this case, the local hostname is <varname>omega</varname>.</para>
 114
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>See Also</title>
 119     <para>
 120       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 121       <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 122       <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 123       <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 124       <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 125       <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 126     </para>
 127   </refsect1>
 128
 129 </refentry>