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">
6 This file is part of systemd.
8 Copyright 2011 Lennart Poettering
9 Copyright 2013 Tom Gundersen
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.
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.
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/>.
25 <refentry id="nss-myhostname" conditional='HAVE_MYHOSTNAME'>
28 <title>nss-myhostname</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>nss-myhostname</refentrytitle>
43 <manvolnum>8</manvolnum>
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>
54 <para><filename>libnss_myhostname.so.2</filename></para>
58 <title>Description</title>
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>
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>
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>
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>
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>
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>
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>
118 <title>Example</title>
120 <para>Here's an example
121 <filename>/etc/nsswitch.conf</filename> file, that
122 enables <command>myhostname</command>
125 <programlisting>passwd: compat
129 hosts: files dns mymachines <command>myhostname</command>
137 netgroup: nis</programlisting>
139 <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
141 <programlisting>$ getent ahosts `hostname`
147 127.0.0.2 RAW</programlisting>
149 <para>In this case the local hostname is <varname>omega</varname>.</para>
154 <title>See Also</title>
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>