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 public
71 IP addresses, or -- if none are configured --
72 the IPv4 address 127.0.0.2 (which is on the
73 local loopback) and the IPv6 address ::1
74 (which is the local host).</para></listitem>
76 <listitem><para>The hostname
77 <literal>localhost</literal> is resolved to
78 the IP addresses 127.0.0.1 and
79 ::1.</para></listitem>
81 <listitem><para>The hostname
82 <literal>gateway</literal> is resolved to all
83 current default routing gateway addresses,
84 ordered by their metric. This assigns a stable
85 hostname to the current gateway, useful for
86 referencing it independently of the current
87 network configuration state.</para></listitem>
91 <para>Various software relies on an always-resolvable
92 local hostname. When using dynamic hostnames, this is
93 traditionally achieved by patching
94 <filename>/etc/hosts</filename> at the same time as
95 changing the hostname. This is problematic since it
96 requires a writable <filename>/etc</filename> file
97 system and is fragile because the file might be edited
98 by the administrator at the same time. With
99 <command>nss-myhostname</command> enabled changing
100 <filename>/etc/hosts</filename> is unncessary, and on
101 many systems the file becomes entirely optional.</para>
103 <para>To activate the NSS modules,
104 <literal>myhostname</literal> has to be added to the
105 line starting with <literal>hosts:</literal> in
106 <filename>/etc/nsswitch.conf</filename>.</para>
108 <para>It is recommended to place
109 <literal>myhostname</literal> last in the
110 <filename>nsswitch.conf</filename> line to make sure
111 that this mapping is only used as fallback, and any
112 DNS or <filename>/etc/hosts</filename> based mapping
113 takes precedence.</para>
117 <title>Example</title>
119 <para>Here's an example
120 <filename>/etc/nsswitch.conf</filename> file, that
121 enables <command>myhostname</command>
124 <programlisting>passwd: compat
128 hosts: files dns <command>myhostname</command>
136 netgroup: nis</programlisting>
138 <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
140 <programlisting>$ getent ahosts `hostname`
146 127.0.0.2 RAW</programlisting>
148 <para>In this case the local hostname is <varname>omega</varname>.</para>
153 <title>See Also</title>
155 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
156 <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
157 <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>