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">
  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 host name resolution for the locally
  49                 configured system hostname.</refpurpose>
  50         </refnamediv>
  51
  52         <refsynopsisdiv>
  53                 <cmdsynopsis>
  54                         <command>nss-myhostname.la</command>
  55                 </cmdsynopsis>
  56         </refsynopsisdiv>
  57
  58         <refsect1>
  59                 <title>Description</title>
  60
  61                 <para><command>nss-myhostname</command> is a plugin for the GNU Name Service Switch
  62                 (NSS) functionality of the GNU C Library (<command>glibc</command>)
  63                 providing host name resolution for the locally configured system
  64                 hostname as returned by
  65                 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
  66                 Various software relies on an always resolvable local host name. When
  67                 using dynamic hostnames this is usually achieved by patching
  68                 <filename>/etc/hosts</filename> at the same time as changing the host
  69                 name. This however is not ideal since it requires a writable
  70                 <filename>/etc</filename> file system and is fragile because the file
  71                 might be edited by the administrator at the same time. <command>nss-myhostname</command>
  72                 simply returns all locally configure public IP addresses, or -- if none
  73                 are configured -- the IPv4 address 127.0.0.2 (wich is on the local
  74                 loopback) and the IPv6 address ::1 (which is the local host) for
  75                 whatever system hostname is configured locally. Patching
  76                 <filename>/etc/hosts</filename> is thus no longer necessary.</para>
  77
  78                 <para>To activate the NSS modules, <option>myhostname</option>
  79                 has to be added to the line starting with "<varname>hosts:</varname>" in
  80                 <filename>/etc/nsswitch.conf</filename></para>
  81
  82                 <para>It is recommended to put <option>myhostname</option>
  83                 last in the <filename>nsswitch.conf</filename> line to make
  84                 sure that this mapping is only used as fallback, and any DNS
  85                 or <filename>/etc/hosts</filename> based mapping takes precedence.</para>
  86         </refsect1>
  87
  88         <refsect1>
  89                 <title>Example</title>
  90
  91                 <programlisting>
  92 # /etc/nsswitch.conf
  93
  94 passwd:         compat
  95 group:          compat
  96 shadow:         compat
  97
  98 hosts:          files dns <varname>myhostname</varname>
  99 networks:       files
 100
 101 protocols:      db files
 102 services:       db files
 103 ethers:         db files
 104 rpc:            db files
 105
 106 netgroup:       nis
 107                 </programlisting>
 108
 109                 <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
 110
 111                 <programlisting>
 112 $ getent ahosts `hostname`
 113 ::1             STREAM omega
 114 ::1             DGRAM
 115 ::1             RAW
 116 127.0.0.2       STREAM
 117 127.0.0.2       DGRAM
 118 127.0.0.2       RAW
 119                 </programlisting>
 120
 121                 <para>In this case the local host name is <varname>omega</varname>.</para>
 122
 123         </refsect1>
 124
 125         <refsect1>
 126                 <title>See Also</title>
 127                 <para>
 128                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 129                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 130                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 131                         <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 132                         <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 133                         <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 134                         <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 135                         <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 136                 </para>
 137         </refsect1>
 138
 139 </refentry>