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                 <refpurpose>Provide hostname resolution for the locally
  49                 configured system hostname.</refpurpose>
  50         </refnamediv>
  51
  52         <refsynopsisdiv>
  53                 <para><filename>libnss_myhostname.so.2</filename></para>
  54         </refsynopsisdiv>
  55
  56         <refsect1>
  57                 <title>Description</title>
  58
  59                 <para><command>nss-myhostname</command> is a plugin
  60                 for the GNU Name Service Switch (NSS) functionality of
  61                 the GNU C Library (<command>glibc</command>) primarily
  62                 providing hostname resolution for the locally
  63                 configured system hostname as returned by
  64                 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. The
  65                 precise hostnames resolved by this module are:</para>
  66
  67                 <itemizedlist>
  68                         <listitem><para>The local, configured hostname
  69                         is resolved to all locally configured public
  70                         IP addresses, or -- if none are configured --
  71                         the IPv4 address 127.0.0.2 (which is on the
  72                         local loopback) and the IPv6 address ::1
  73                         (which is the local host).</para></listitem>
  74
  75                         <listitem><para>The hostname
  76                         <literal>localhost</literal> is resolved to
  77                         the IP addresses 127.0.0.1 and
  78                         ::1.</para></listitem>
  79
  80                         <listitem><para>The hostname
  81                         <literal>gateway</literal> is resolved to all
  82                         current default routing gateway addresses,
  83                         ordered by their metric. This assigns a stable
  84                         hostname to the current gateway, useful for
  85                         referencing it independently of the current
  86                         network configuration state.</para></listitem>
  87
  88                 </itemizedlist>
  89
  90                 <para>Various software relies on an always-resolvable
  91                 local hostname. When using dynamic hostnames, this is
  92                 traditionally achieved by patching
  93                 <filename>/etc/hosts</filename> at the same time as
  94                 changing the hostname. This is problematic since it
  95                 requires a writable <filename>/etc</filename> file
  96                 system and is fragile because the file might be edited
  97                 by the administrator at the same time. With
  98                 <command>nss-myhostname</command> enabled changing
  99                 <filename>/etc/hosts</filename> is unncessary, and on
 100                 many systems the file becomes entirely optional.</para>
 101
 102                 <para>To activate the NSS modules,
 103                 <literal>myhostname</literal> has to be added to the
 104                 line starting with <literal>hosts:</literal> in
 105                 <filename>/etc/nsswitch.conf</filename>.</para>
 106
 107                 <para>It is recommended to place
 108                 <literal>myhostname</literal> last in the
 109                 <filename>nsswitch.conf</filename> line to make sure
 110                 that this mapping is only used as fallback, and any
 111                 DNS or <filename>/etc/hosts</filename> based mapping
 112                 takes precedence.</para>
 113         </refsect1>
 114
 115         <refsect1>
 116                 <title>Example</title>
 117
 118                 <para>Here's an example
 119                 <filename>/etc/nsswitch.conf</filename> file, that
 120                 enables <command>myhostname</command>
 121                 correctly:</para>
 122
 123 <programlisting>passwd:         compat
 124 group:          compat
 125 shadow:         compat
 126
 127 hosts:          files dns <command>myhostname</command>
 128 networks:       files
 129
 130 protocols:      db files
 131 services:       db files
 132 ethers:         db files
 133 rpc:            db files
 134
 135 netgroup:       nis</programlisting>
 136
 137                 <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
 138
 139                 <programlisting>$ getent ahosts `hostname`
 140 ::1             STREAM omega
 141 ::1             DGRAM
 142 ::1             RAW
 143 127.0.0.2       STREAM
 144 127.0.0.2       DGRAM
 145 127.0.0.2       RAW</programlisting>
 146
 147                 <para>In this case the local hostname is <varname>omega</varname>.</para>
 148
 149         </refsect1>
 150
 151         <refsect1>
 152                 <title>See Also</title>
 153                 <para>
 154                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 155                         <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 156                         <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 157                 </para>
 158         </refsect1>
 159
 160 </refentry>