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