src/nss-myhostname/doc/README.html.in

   1 <?xml version="1.0" encoding="iso-8859-1"?> <!-- -*-html-helper-*- -->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4
   5 <head>
   6 <title>nss-myhostname @PACKAGE_VERSION@</title>
   7 <link rel="stylesheet" type="text/css" href="style.css" />
   8 </head>
   9
  10 <body>
  11 <h1><a name="top">nss-myhostname @PACKAGE_VERSION@</a></h1>
  12
  13 <p><i>Copyright 2005-2011 Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;</i></p>
  14
  15 <ul class="toc">
  16     <li><a href="#license">License</a></li>
  17     <li><a href="#news">News</a></li>
  18     <li><a href="#overview">Overview</a></li>
  19     <li><a href="#status">Current Status</a></li>
  20     <li><a href="#documentation">Documentation</a></li>
  21     <li><a href="#requirements">Requirements</a></li>
  22     <li><a href="#installation">Installation</a></li>
  23     <li><a href="#acks">Acknowledgements</a></li>
  24     <li><a href="#download">Download</a></li>
  25 </ul>
  26
  27 <h2><a name="license">License</a></h2>
  28
  29 <p>This program is free software; you can redistribute it and/or
  30 modify it under the terms of the GNU Lesser General Public License as
  31 published by the Free Software Foundation, either version 2.1 of the
  32 License, or (at your option) any later version.</p>
  33
  34 <p>This program is distributed in the hope that it will be useful, but
  35 WITHOUT ANY WARRANTY; without even the implied warranty of
  36 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  37 Lesser General Public License for more details.</p>
  38
  39 <h2><a name="news">News</a></h2>
  40
  41 <div class="news-date">Mon May 9 2011: </div>
  42
  43 <p class="news-text"><a href="@PACKAGE_URL@nss-myhostname-0.3.tar.gz">Version
  44 0.3</a> released. Changes include: Always return locally configured IP
  45 addresses first, use 127.0.0.2/::1 only as fallback if no addresses
  46 are configured.</p>
  47
  48 <div class="news-date">Mon Oct 27 2008: </div>
  49
  50 <p class="news-text"><a
  51 href="@PACKAGE_URL@nss-myhostname-0.2.tar.gz">Version 0.2</a>
  52 released. Changes include: Update for IPv6 and newest glibc NSS interfaces</p>
  53
  54 <div class="news-date">Sat Nov 19 2005: </div>
  55
  56 <p class="news-text"><a
  57 href="@PACKAGE_URL@nss-myhostname-0.1.tar.gz">Version 0.1</a>
  58 released. Initial release.</p>
  59
  60 <h2><a name="overview">Overview</a></h2>
  61
  62 <p><tt>nss-myhostname</tt> is a plugin for the GNU Name Service Switch
  63 (NSS) functionality of the GNU C Library (<tt>glibc</tt>) providing
  64 host name resolution for the locally configured system hostname as
  65 returned by <tt>gethostname(2)</tt>. Various software relies on an
  66 always resolvable local host name. When using dynamic hostnames this
  67 is usually achieved by patching <tt>/etc/hosts</tt> at the same time
  68 as changing the host name. This however is not ideal since it requires
  69 a writable <tt>/etc</tt> file system and is fragile because the file
  70 might be edited by the administrator at the same
  71 time. <tt>nss-myhostname</tt> simply returns all locally configure
  72 public IP addresses, or -- if none are configured -- the IPv4
  73 address <tt>127.0.0.2</tt> (wich is on the local loopback) and the
  74 IPv6 address <tt>::1</tt> (which is the local host) for whatever
  75 system hostname is configured locally. Patching <tt>/etc/hosts</tt>
  76 is thus no longer necessary.</p>
  77
  78 <h2><a name="status">Current Status</a></h2>
  79
  80 <p>It works!</p>
  81
  82 <h2><a name="documentation">Documentation</a></h2>
  83
  84 <p>After compiling and installing <tt>nss-myhostname</tt> you'll find a
  85 new NSS modules in <tt>/lib</tt>:</p>
  86 <ul>
  87 <li><tt>libnss_myhostname.so.2</tt></li>
  88 </ul>
  89
  90 <p>To activate the NSS modules you have to edit
  91 <tt>/etc/nsswitch.conf</tt> and add <tt>myhostname</tt> to the
  92 line starting with "<tt>hosts:</tt>". On Debian this looks like
  93 this:</p>
  94
  95 <pre># /etc/nsswitch.conf
  96
  97 passwd:         compat
  98 group:          compat
  99 shadow:         compat
 100
 101 hosts:          files dns <b>myhostname</b>
 102 networks:       files
 103
 104 protocols:      db files
 105 services:       db files
 106 ethers:         db files
 107 rpc:            db files
 108
 109 netgroup:       nis</pre>
 110
 111 <p>That's it. You should now always be able to resolve your local
 112 system hostname. For a quick check
 113 use <tt>glibc</tt>'s <tt>getent</tt> tool:
 114
 115 <pre>$ getent ahosts `hostname`
 116 ::1             STREAM omega
 117 ::1             DGRAM
 118 ::1             RAW
 119 127.0.0.2       STREAM
 120 127.0.0.2       DGRAM
 121 127.0.0.2       RAW
 122 </pre>
 123
 124 <p>In this case the local host name is <i>omega</i>.</p>
 125
 126 <p>It is recommended to put <tt>myhostname</tt> last in
 127 the <tt>nsswitch.conf</tt> line to make sure that this mapping is only
 128 used as fallback, and any DNS or <tt>/etc/hosts</tt> based mapping takes
 129 precedence.</p>
 130
 131 <h2><a name="requirements">Requirements</a></h2>
 132
 133 <p><tt>nss-myhostname</tt> uses NSS interfaces that are specific to modern <tt>glibc</tt>'s.</p>
 134
 135 <p><tt>nss-myhostname</tt> was developed and tested on Fedora 15 from
 136 May 2011, it should work on most other Linux distributions since it
 137 uses GNU autoconf and GNU libtool for source code configuration and
 138 shared library management.</p>
 139
 140 <h2><a name="installation">Installation</a></h2>
 141
 142 <p>As this package is made with the GNU autotools you should run
 143 <tt>./configure</tt> inside the distribution directory for configuring
 144 the source tree. After that you should run <tt>make</tt> for
 145 compilation and <tt>make install</tt> (as root) for installation of
 146 <tt>nss-myhostname</tt>.</p>
 147
 148 <h2><a name="acks">Acknowledgements</a></h2>
 149
 150 <p>None so far.</p>
 151
 152 <h2><a name="download">Download</a></h2>
 153
 154 <p>The newest release is always available from <a href="@PACKAGE_URL@">@PACKAGE_URL@</a></p>
 155
 156 <p>The current release is <a href="@PACKAGE_URL@nss-myhostname-@PACKAGE_VERSION@.tar.gz">@PACKAGE_VERSION@</a></p>
 157
 158 <p>Get <tt>nss-myhostname</tt>'s development sources from the <a href="http://git.or.cz/">GIT</a> <a href="git://git.0pointer.de/nss-myhostname">repository</a> (<a href="http://git.0pointer.de/?p=nss-myhostname.git">gitweb</a>): </p>
 159
 160 <pre>git clone git://git.0pointer.de/nss-myhostname</pre>
 161
 162 <hr/>
 163 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, May 2011</address>
 164
 165 </body>
 166 </html>