diff options
| -rw-r--r-- | man/nss-myhostname.xml | 32 | ||||
| -rw-r--r-- | man/nss-mymachines.xml | 43 | ||||
| -rw-r--r-- | man/nss-resolve.xml | 45 |
3 files changed, 51 insertions, 69 deletions
diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index 251bdecbad..f8837745ae 100644 --- a/man/nss-myhostname.xml +++ b/man/nss-myhostname.xml @@ -57,12 +57,11 @@ <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> + <para><command>nss-myhostname</command> is a plug-in module 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 @@ -80,7 +79,6 @@ 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 @@ -93,29 +91,25 @@ 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>To activate the NSS modules, add <literal>myhostname</literal> 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 that any DNS or - <filename>/etc/hosts</filename> based mapping takes - precedence.</para> + <para>It is recommended to place <literal>myhostname</literal> last in the <filename>nsswitch.conf</filename>' + <literal>hosts:</literal> line to make sure that this mapping is only used as fallback, and that any DNS or + <filename>/etc/hosts</filename> based mapping takes precedence.</para> </refsect1> <refsect1> <title>Example</title> - <para>Here is an example <filename>/etc/nsswitch.conf</filename> - file that enables <command>myhostname</command> correctly:</para> + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables + <command>nss-myhostname</command> correctly:</para> <programlisting>passwd: compat mymachines group: compat mymachines shadow: compat -hosts: files resolve mymachines <command>myhostname</command> +hosts: files mymachines resolve <command>myhostname</command> networks: files protocols: db files diff --git a/man/nss-mymachines.xml b/man/nss-mymachines.xml index d2bec763bb..ec047449bf 100644 --- a/man/nss-mymachines.xml +++ b/man/nss-mymachines.xml @@ -56,42 +56,37 @@ <refsect1> <title>Description</title> - <para><command>nss-mymachines</command> is a plugin for the GNU - Name Service Switch (NSS) functionality of the GNU C Library - (<command>glibc</command>), providing hostname resolution for - container names of containers running locally that are registered - with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - The container names are resolved to the IP addresses of the - specific container, ordered by their scope.</para> - - <para>The module also resolves user IDs used by containers to user - names indicating the container name, and back.</para> - - <para>To activate the NSS modules, <literal>mymachines</literal> - has to be added to the lines starting with - <literal>hosts:</literal>, <literal>passwd:</literal> and - <literal>group:</literal> in + <para><command>nss-mymachines</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of + the GNU C Library (<command>glibc</command>), providing hostname resolution for the names of containers running + locally that are registered with + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The + container names are resolved to the IP addresses of the specific container, ordered by their scope. This + functionality only applies to containers using network namespacing.</para> + + <para>The module also resolves user and group IDs used by containers to user and group names indicating the + container name, and back. This functionality only applies to containers using user namespacing.</para> + + <para>To activate the NSS module, add <literal>mymachines</literal> to the lines starting with + <literal>hosts:</literal>, <literal>passwd:</literal> and <literal>group:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> - <para>It is recommended to place <literal>mymachines</literal> - near the end of the <filename>nsswitch.conf</filename> lines to - make sure that its mappings are only used as fallback, and that any - other mappings, such as DNS or <filename>/etc/hosts</filename> - based mappings, take precedence.</para> + <para>It is recommended to place <literal>mymachines</literal> after the <literal>files</literal> or + <literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines to make sure that its mappings + are preferred over other resolvers such as DNS, but so that <filename>/etc/hosts</filename>, + <filename>/etc/passwd</filename> and <filename>/etc/group</filename> based mappings take precedence.</para> </refsect1> <refsect1> <title>Example</title> - <para>Here is an example <filename>/etc/nsswitch.conf</filename> - file that enables <command>mymachines</command> correctly:</para> + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables + <command>nss-mymachines</command> correctly:</para> <programlisting>passwd: compat <command>mymachines</command> group: compat <command>mymachines</command> shadow: compat -hosts: files resolve <command>mymachines</command> myhostname +hosts: files <command>mymachines</command> resolve myhostname networks: files protocols: db files diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml index 8b0928145f..d9e56453e8 100644 --- a/man/nss-resolve.xml +++ b/man/nss-resolve.xml @@ -56,37 +56,36 @@ <refsect1> <title>Description</title> - <para><command>nss-resolve</command> is a plugin module for the - GNU Name Service Switch (NSS) functionality of the GNU C Library - (<command>glibc</command>) enabling it to resolve host names via - the - <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> - local network name resolution service.</para> - - <para>To activate the NSS module, <literal>resolve</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>resolve</literal> early - in the <filename>nsswitch.conf</filename> line (but after the - <literal>files</literal> entry), replacing the - <literal>dns</literal> entry if it exists, to ensure DNS queries - are always routed via + <para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the + GNU C Library (<command>glibc</command>) enabling it to resolve host names via the + <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> local network + name resolution service. It replaces the <command>nss-dns</command> plug-in module that traditionally resolves + hostnames via DNS.</para> + + <para>To activate the NSS module, add <literal>resolve</literal> to the line starting with + <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> + + <para>It is recommended to place <literal>resolve</literal> early in <filename>/etc/nsswitch.conf</filename>' + <literal>hosts:</literal> line (but after the <literal>files</literal> or <literal>mymachines</literal> entries), + replacing the <literal>dns</literal> entry if it exists, to ensure DNS queries are always routed via <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>Note that <command>nss-resolve</command> will chain-load <command>nss-dns</command> if + <filename>systemd-resolved.service</filename> is not running, ensuring that basic DNS resolution continues to work + if the service is down.</para> </refsect1> <refsect1> <title>Example</title> - <para>Here is an example <filename>/etc/nsswitch.conf</filename> - file that enables <command>resolve</command> correctly:</para> + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-resolve</command> + correctly:</para> <programlisting>passwd: compat mymachines group: compat mymachines shadow: compat -hosts: files <command>resolve</command> mymachines myhostname +hosts: files mymachines <command>resolve</command> myhostname networks: files protocols: db files @@ -96,12 +95,6 @@ rpc: db files netgroup: nis</programlisting> - <para>Note that <command>nss-resolve</command> will chain-load - <command>nss-dns</command> if - <filename>systemd-resolved.service</filename> is not running, - ensuring that basic DNS resolution continues to work if the - service is down.</para> - </refsect1> <refsect1> |