X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fnss-myhostname.xml;h=cf2b0200f2e16ede7604afbc0d13765fbf043f4a;hb=5c3072eab6d2e11d89452987b017541d4654ac05;hp=c0e2b828be13b5d38c8bd0e3b36181a51e0cc24b;hpb=7d7681f70bc8c2140092029ccada9f75510a176b;p=elogind.git

diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml
index c0e2b828b..cf2b0200f 100644
--- a/man/nss-myhostname.xml
+++ b/man/nss-myhostname.xml
@@ -1,6 +1,6 @@
 <?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">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
@@ -24,114 +24,129 @@
 
 <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>
-                <refpurpose>Provide host name resolution for the locally
-                configured system hostname.</refpurpose>
-        </refnamediv>
-
-        <refsynopsisdiv>
-                <para><filename>nss-myhostname.la</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>)
-                providing host name resolution for the locally configured system
-                hostname as returned by
-                <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
-                Various software relies on an always resolvable local host name. When
-                using dynamic hostnames this is usually achieved by patching
-                <filename>/etc/hosts</filename> at the same time as changing the host
-                name. This however is not ideal 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. <command>nss-myhostname</command>
-                simply returns all locally configure public IP addresses, 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) for
-                whatever system hostname is configured locally. Patching
-                <filename>/etc/hosts</filename> is thus no longer necessary.</para>
-
-                <para>To activate the NSS modules, <option>myhostname</option>
-                has to be added to the line starting with "<varname>hosts:</varname>" in
-                <filename>/etc/nsswitch.conf</filename></para>
-
-                <para>It is recommended to put <option>myhostname</option>
-                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>
-
-                <programlisting>
-# /etc/nsswitch.conf
-
-passwd:         compat
-group:          compat
-shadow:         compat
-
-hosts:          files dns <varname>myhostname</varname>
+  <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
+ethers:   db files
+rpc:      db files
 
-netgroup:       nis
-                </programlisting>
+netgroup:       nis</programlisting>
 
-                <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
+    <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para>
 
-                <programlisting>
-$ getent ahosts `hostname`
-::1             STREAM omega
-::1             DGRAM
-::1             RAW
+    <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 host name is <varname>omega</varname>.</para>
-
-        </refsect1>
-
-        <refsect1>
-                <title>See Also</title>
-                <para>
-                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-                </para>
-        </refsect1>
+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>