diff options
Diffstat (limited to 'man/nss-myhostname.xml')
| -rw-r--r-- | man/nss-myhostname.xml | 233 |
1 files changed, 111 insertions, 122 deletions
diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index c7a2cd9ae7..cf2b0200f2 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,140 +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> - <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> + <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> - <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 hostname is <varname>omega</varname>.</para> + <para>In this case the local hostname is <varname>omega</varname>.</para> - </refsect1> + </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> + <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> |