<?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 unncessary, 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

group: compat

shadow: compat

hosts: files dns 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-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>