16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen This file is part of systemd.
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen Copyright 2011 Lennart Poettering
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen Copyright 2013 Tom Gundersen
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen systemd is free software; you can redistribute it and/or modify it
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen under the terms of the GNU Lesser General Public License as published by
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen the Free Software Foundation; either version 2.1 of the License, or
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen (at your option) any later version.
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen systemd is distributed in the hope that it will be useful, but
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen WITHOUT ANY WARRANTY; without even the implied warranty of
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen Lesser General Public License for more details.
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen You should have received a copy of the GNU Lesser General Public License
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen along with systemd; If not, see <http://www.gnu.org/licenses/>.
56ba3c78ae35065064c4289a0c8e22a81256af20Zbigniew Jędrzejewski-Szmek<refentry id="nss-myhostname" conditional='HAVE_MYHOSTNAME'>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>nss-myhostname</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>nss-myhostname</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>libnss_myhostname.so.2</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Provide hostname resolution for the locally
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek configured system hostname.</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><filename>libnss_myhostname.so.2</filename></para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><command>nss-myhostname</command> is a plugin for the GNU
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Name Service Switch (NSS) functionality of the GNU C Library
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt (<command>glibc</command>), primarily providing hostname resolution
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for the locally configured system hostname as returned by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek The precise hostnames resolved by this module are:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>The local, configured hostname is resolved to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek all locally configured IP addresses ordered by their scope, or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek — if none are configured — the IPv4 address 127.0.0.2 (which
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is on the local loopback) and the IPv6 address ::1 (which is the
358a9d51147f721c3e1701ea7df3522ca049254cLennart Poettering <listitem><para>The hostname <literal>localhost</literal> (as well as any hostname ending in
358a9d51147f721c3e1701ea7df3522ca049254cLennart Poettering <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is
358a9d51147f721c3e1701ea7df3522ca049254cLennart Poettering resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>The hostname <literal>gateway</literal> is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek resolved to all current default routing gateway addresses,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek ordered by their metric. This assigns a stable hostname to the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek current gateway, useful for referencing it independently of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek current network configuration state.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Various software relies on an always-resolvable local
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek hostname. When using dynamic hostnames, this is traditionally
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek achieved by patching <filename>/etc/hosts</filename> at the same
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek time as changing the hostname. This is problematic since it
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek requires a writable <filename>/etc</filename> file system and is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek fragile because the file might be edited by the administrator at
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt the same time. With <command>nss-myhostname</command> enabled,
ff9b60f38bf68eba4a47cabff14547d92e083214Torstein Husebø changing <filename>/etc/hosts</filename> is unnecessary, and on
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt many systems, the file becomes entirely optional.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>To activate the NSS modules, <literal>myhostname</literal>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek has to be added to the line starting with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/etc/nsswitch.conf</filename>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>It is recommended to place <literal>myhostname</literal>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek last in the <filename>nsswitch.conf</filename> line to make sure
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt that this mapping is only used as fallback, and that any DNS or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/etc/hosts</filename> based mapping takes
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek precedence.</para>
7ca4155737730ece73ae4b4ac80571005cb99b69Jan Engelhardt <para>Here is an example <filename>/etc/nsswitch.conf</filename>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt file that enables <command>myhostname</command> correctly:</para>
a8ba86ce6a78f2bd80529e535af3494bf8297cfdLennart Poettering<programlisting>passwd: compat mymachines
a8ba86ce6a78f2bd80529e535af3494bf8297cfdLennart Poetteringgroup: compat mymachines
0d6868f9ae83c06b23676eec0726e1f37adce30eLennart Poetteringhosts: files resolve mymachines <command>myhostname</command>
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersennetworks: files
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersenprotocols: db files
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersenservices: db files
0d6868f9ae83c06b23676eec0726e1f37adce30eLennart Poetteringethers: db files
9fccdb0f64d12bc09a71442dd0af2248c1aa3e89Lennart Poetteringnetgroup: nis</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting>$ getent ahosts `hostname`
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen127.0.0.2 STREAM
16eb4da97e1bfe7f9416a0622b1a06408e550423Tom Gundersen127.0.0.2 DGRAM
9fccdb0f64d12bc09a71442dd0af2248c1aa3e89Lennart Poettering127.0.0.2 RAW</programlisting>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>In this case, the local hostname is <varname>omega</varname>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
0d6868f9ae83c06b23676eec0726e1f37adce30eLennart Poettering <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>