<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="nss-myhostname" conditional='HAVE_MYHOSTNAME'>

<refentryinfo>

<title>nss-myhostname</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>nss-myhostname</refentrytitle>

<manvolnum>8</manvolnum>

</refmeta>

<refnamediv>

<refname>nss-myhostname</refname>

<refname>libnss_myhostname.so.2</refname>

<refpurpose>Provide hostname resolution for the locally

configured system hostname.</refpurpose>

</refnamediv>

<refsynopsisdiv>

<para><filename>libnss_myhostname.so.2</filename></para>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><command>nss-myhostname</command> is a plugin for the GNU

Name Service Switch (NSS) functionality of the GNU C Library

(<command>glibc</command>), primarily providing hostname resolution

for the locally configured system hostname as returned by

<citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.

The precise hostnames resolved by this module are:</para>

<itemizedlist>

<listitem><para>The local, configured hostname is resolved to

all locally configured IP addresses ordered by their scope, or

— if none are configured — the IPv4 address 127.0.0.2 (which

is on the local loopback) and the IPv6 address ::1 (which is the

local host).</para></listitem>

<listitem><para>The hostname <literal>localhost</literal> is

resolved to the IP addresses 127.0.0.1 and

::1.</para></listitem>

<listitem><para>The hostname <literal>gateway</literal> is

resolved to all current default routing gateway addresses,

ordered by their metric. This assigns a stable hostname to the

current gateway, useful for referencing it independently of the

current network configuration state.</para></listitem>

</itemizedlist>

<para>Various software relies on an always-resolvable local

hostname. When using dynamic hostnames, this is traditionally

achieved by patching <filename>/etc/hosts</filename> at the same

time as changing the hostname. This is problematic since it

requires a writable <filename>/etc</filename> file system and is

fragile because the file might be edited by the administrator at

the same time. With <command>nss-myhostname</command> enabled,

changing <filename>/etc/hosts</filename> is unnecessary, and on

many systems, the file becomes entirely optional.</para>

<para>To activate the NSS modules, <literal>myhostname</literal>

has to be added to the line starting with

<literal>hosts:</literal> in

<filename>/etc/nsswitch.conf</filename>.</para>

<para>It is recommended to place <literal>myhostname</literal>

last in the <filename>nsswitch.conf</filename> line to make sure

that this mapping is only used as fallback, and any DNS or

<filename>/etc/hosts</filename> based mapping takes

precedence.</para>

</refsect1>

<refsect1>

<title>Example</title>

<para>Here's an example <filename>/etc/nsswitch.conf</filename>

file that enables <command>myhostname</command> correctly:</para>

<programlisting>passwd: compat mymachines

group: compat mymachines

shadow: compat

hosts: files resolve mymachines <command>myhostname</command>

networks: files

protocols: db files

services: db files

ethers: db files

rpc: db files

netgroup: nis</programlisting>

<para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>

<programlisting>$ getent ahosts `hostname`

::1 STREAM omega

::1 DGRAM

::1 RAW

127.0.0.2 STREAM

127.0.0.2 DGRAM

127.0.0.2 RAW</programlisting>

<para>In this case, the local hostname is <varname>omega</varname>.</para>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

<citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>