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