man/nss-myhostname.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2011 Lennart Poettering
   9   Copyright 2013 Tom Gundersen
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 -->
  24
  25 <refentry id="nss-myhostname" conditional='HAVE_MYHOSTNAME'>
  26
  27         <refentryinfo>
  28                 <title>nss-myhostname</title>
  29                 <productname>systemd</productname>
  30
  31                 <authorgroup>
  32                         <author>
  33                                 <contrib>Developer</contrib>
  34                                 <firstname>Lennart</firstname>
  35                                 <surname>Poettering</surname>
  36                                 <email>lennart@poettering.net</email>
  37                         </author>
  38                 </authorgroup>
  39         </refentryinfo>
  40
  41         <refmeta>
  42                 <refentrytitle>nss-myhostname</refentrytitle>
  43                 <manvolnum>8</manvolnum>
  44         </refmeta>
  45
  46         <refnamediv>
  47                 <refname>nss-myhostname</refname>
  48                 <refname>libnss_myhostname.so.2</refname>
  49                 <refpurpose>Provide hostname resolution for the locally
  50                 configured system hostname.</refpurpose>
  51         </refnamediv>
  52
  53         <refsynopsisdiv>
  54                 <para><filename>libnss_myhostname.so.2</filename></para>
  55         </refsynopsisdiv>
  56
  57         <refsect1>
  58                 <title>Description</title>
  59
  60                 <para><command>nss-myhostname</command> is a plugin
  61                 for the GNU Name Service Switch (NSS) functionality of
  62                 the GNU C Library (<command>glibc</command>) primarily
  63                 providing hostname resolution for the locally
  64                 configured system hostname as returned by
  65                 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. The
  66                 precise hostnames resolved by this module are:</para>
  67
  68                 <itemizedlist>
  69                         <listitem><para>The local, configured hostname
  70                         is resolved to all locally configured public
  71                         IP addresses, or -- if none are configured --
  72                         the IPv4 address 127.0.0.2 (which is on the
  73                         local loopback) and the IPv6 address ::1
  74                         (which is the local host).</para></listitem>
  75
  76                         <listitem><para>The hostname
  77                         <literal>localhost</literal> is resolved to
  78                         the IP addresses 127.0.0.1 and
  79                         ::1.</para></listitem>
  80
  81                         <listitem><para>The hostname
  82                         <literal>gateway</literal> is resolved to all
  83                         current default routing gateway addresses,
  84                         ordered by their metric. This assigns a stable
  85                         hostname to the current gateway, useful for
  86                         referencing it independently of the current
  87                         network configuration state.</para></listitem>
  88
  89                 </itemizedlist>
  90
  91                 <para>Various software relies on an always-resolvable
  92                 local hostname. When using dynamic hostnames, this is
  93                 traditionally achieved by patching
  94                 <filename>/etc/hosts</filename> at the same time as
  95                 changing the hostname. This is problematic since it
  96                 requires a writable <filename>/etc</filename> file
  97                 system and is fragile because the file might be edited
  98                 by the administrator at the same time. With
  99                 <command>nss-myhostname</command> enabled changing
 100                 <filename>/etc/hosts</filename> is unncessary, and on
 101                 many systems the file becomes entirely optional.</para>
 102
 103                 <para>To activate the NSS modules,
 104                 <literal>myhostname</literal> has to be added to the
 105                 line starting with <literal>hosts:</literal> in
 106                 <filename>/etc/nsswitch.conf</filename>.</para>
 107
 108                 <para>It is recommended to place
 109                 <literal>myhostname</literal> last in the
 110                 <filename>nsswitch.conf</filename> line to make sure
 111                 that this mapping is only used as fallback, and any
 112                 DNS or <filename>/etc/hosts</filename> based mapping
 113                 takes precedence.</para>
 114         </refsect1>
 115
 116         <refsect1>
 117                 <title>Example</title>
 118
 119                 <para>Here's an example
 120                 <filename>/etc/nsswitch.conf</filename> file, that
 121                 enables <command>myhostname</command>
 122                 correctly:</para>
 123
 124 <programlisting>passwd:         compat
 125 group:          compat
 126 shadow:         compat
 127
 128 hosts:          files dns <command>myhostname</command>
 129 networks:       files
 130
 131 protocols:      db files
 132 services:       db files
 133 ethers:         db files
 134 rpc:            db files
 135
 136 netgroup:       nis</programlisting>
 137
 138                 <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
 139
 140                 <programlisting>$ getent ahosts `hostname`
 141 ::1             STREAM omega
 142 ::1             DGRAM
 143 ::1             RAW
 144 127.0.0.2       STREAM
 145 127.0.0.2       DGRAM
 146 127.0.0.2       RAW</programlisting>
 147
 148                 <para>In this case the local hostname is <varname>omega</varname>.</para>
 149
 150         </refsect1>
 151
 152         <refsect1>
 153                 <title>See Also</title>
 154                 <para>
 155                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 156                         <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 157                         <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 158                 </para>
 159         </refsect1>
 160
 161 </refentry>