9:51 a.m.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/meson.build | 2 +-
docs/nss.html.in | 189 -----------------------------------------------
docs/nss.rst | 154 ++++++++++++++++++++++++++++++++++++++
3 files changed, 155 insertions(+), 190 deletions(-)
delete mode 100644 docs/nss.html.in
create mode 100644 docs/nss.rst
diff --git a/docs/meson.build b/docs/meson.build
index 087afb15d9..3bdea1407d 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -51,7 +51,6 @@ docs_html_in_files = [
'internals',
'java',
'logging',
- 'nss',
'pci-hotplug',
'php',
'python',
@@ -103,6 +102,7 @@ docs_rst_files = [
'macos',
'migration',
'newreposetup',
+ 'nss',
'pci-addresses',
'platforms',
'programming-languages',
diff --git a/docs/nss.html.in b/docs/nss.html.in
deleted file mode 100644
index 5c58d1bd49..0000000000
--- a/docs/nss.html.in
+++ /dev/null
@@ -1,189 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Libvirt NSS module</h1>
-
- <ul id="toc"></ul>
-
- <p>
- When it comes to managing guests and executing commands inside them, logging
- into guest operating system and doing the job is convenient. Users are used
- to ssh in this case. Ideally:
- </p>
-
- <code>ssh user@virtualMachine</code>
-
- <p>
- would be nice. But depending on virtual network configuration it might not
- be always possible. For instance, when using libvirt NATed network it's
- dnsmasq (spawned by libvirt) who assigns IP addresses to domains. But by
- default, the dnsmasq process is then not consulted when it comes to host
- name translation. Users work around this problem by configuring their
- libvirt network to assign static IP addresses and maintaining
- <code>/etc/hosts</code> file in sync. But this puts needless burden onto
- users. This is where NSS module comes handy.
- </p>
-
- <h2><a id="Installation">Installation</a></h2>
-
- <p>
- Installing the module is really easy:
- </p>
-
-<pre>
-# yum install libvirt-nss
-</pre>
-
- <h2><a id="Configuration">Configuration</a></h2>
-
- <p>
- Enabling the module is really easy. Just add <b>libvirt</b> into
- <code>/etc/nsswitch.conf</code> file. For instance:
- </p>
-
-<pre>
-$ cat /etc/nsswitch.conf
-# /etc/nsswitch.conf:
-passwd: compat
-shadow: compat
-group: compat
-hosts: files libvirt dns
-# ...
-</pre>
-
- <p>
- So, in this specific case, whenever ssh program is looking up the host user
- is trying to connect to, <b>files</b> module is consulted first (which
- boils down to looking up the host name in <code>/etc/hosts</code> file),
if
- not found <b>libvirt</b> module is consulted then. The DNS is the last
- effort then, if none of the previous modules matched the host in question.
- Therefore users should consider the order in which they want the modules to
- lookup given host name.
- </p>
-
- <h2><a id="Sources">Sources of
information</a></h2>
-
- <p>
- As of <code>v3.0.0</code> release, libvirt offers two NSS modules
- implementing two different methods of hostname translation. The first and
- older method is implemented by <code>libvirt</code> plugin and
- basically looks up the hostname to IP address translation in DHCP server
- records. Therefore this is dependent on hostname provided by guests. Thing
- is, not all the guests out there provide one in DHCP transactions, or not
- every sysadmin out there believes all the guests. Hence libvirt implements
- second method in <code>libvirt_guest</code> module which does libvirt
guest
- name to IP address translation (regardless of hostname set in the guest).
- </p>
-
- <p>
- To enable either of the modules put their name into the
- <code>nsswitch.conf</code> file. For instance, to enable
- <code>libvirt_guest</code> module:
- </p>
-
-<pre>
-$ cat /etc/nsswitch.conf
-# /etc/nsswitch.conf:
-hosts: files libvirt_guest dns
-# ...
-</pre>
- <p>Or users can enable both at the same time:</p>
-<pre>
-$ cat /etc/nsswitch.conf
-# /etc/nsswitch.conf:
-hosts: files libvirt libvirt_guest dns
-# ...
-</pre>
-
- <p>
- This configuration will mean that if hostname is not found by the
- <code>libvirt</code> module (e.g. because a guest did not sent hostname
- during DHCP transaction), the <code>libvirt_guest</code> module is
- consulted (and if the hostname matches libvirt guest name it will be
- resolved).
- </p>
-
- <h2><a id="Internals">How does it work?</a></h2>
-
- <p>
- Whenever an Unix process wants to do a host name translation
- <a
href="https://linux.die.net/man/3/gethostbyname"><code>...
- or some variant of it is called. This is a glibc function that takes a
- string containing the host name, crunch it and produces a list of IP
- addresses assigned to that host. Now, glibc developers made a really good
- decision when implementing the internals of the function when they decided
- to make the function pluggable. Since there can be several sources for the
- records (e.g. <code>/etc/hosts</code> file, DNS, LDAP, etc.) it would
not
- make much sense to create one big implementation containing all possible
- cases. What they have done instead is this pluggable mechanism. Small
- plugins implementing nothing but specific technology for lookup process are
- provided and the function then calls those plugins. There is just one
- configuration file that instructs the lookup function in which order should
- the plugins be called and which plugins should be loaded. For more info
- reading <a
href="https://en.wikipedia.org/wiki/Name_Service_Switch">wiki
- page</a> is recommended.
- </p>
-
- <p>
- And this is point where libvirt comes in. Libvirt provides plugin for the
- NSS ecosystem. For some time now libvirt keeps a list of assigned IP
- addresses for libvirt networks. The NSS plugin does no more than search the
- list trying to find matching record for given host name. When found,
- matching IP address is returned to the caller. If not found, translation
- process continues with the next plugin configured. At this point it is
- important to stress the order in which plugins are called. Users should be
- aware that a hostname might match in multiple plugins and right after first
- match, translation process is terminated and no other plugin is consulted.
- Therefore, if there are two different records for the same host name users
- should carefully chose the lookup order.
- </p>
-
- <h2><a id="Limitations">Limitations</a></h2>
-
- <ol>
- <li>The <code>libvirt</code> NSS module matches only hostnames
provided by guest.
- If the libvirt name and one advertised by guest differs, the latter is
- matched. However, as of <code>v3.0.0</code> there are two libvirt NSS
modules
- translating both hostnames provided by guest and libvirt guest names.</li>
- <li>The module works only in that cases where IP addresses are assigned by
- dnsmasq spawned by libvirt. Libvirt NATed networks are typical
- example.</li>
- </ol>
-
- <p>
- <i>The following paragraph describes implementation limitation of the
- <code>libvirt</code> NSS module.</i>
- These limitation are result of libvirt's internal implementation. While
- libvirt can report IP addresses regardless of their origin, a public API
- must be used to obtain those. However, for the API a connection object is
- required. Doing that for every name translation request would be too
- costly. Fortunately, libvirt spawns dnsmasq for NATed networks. Not only
- that, it provides small executable that on each IP address space change
- updates an internal list of addresses thus keeping it in sync. The NSS
- module then merely consults the list trying to find the match. Users can
- view the list themselves:
- </p>
-
-<pre>
-virsh net-dhcp-leases $network
-</pre>
-
- <p>
- where <code>$network</code> iterates through all running networks. So the
module
- does merely the same as
- </p>
-
-<pre>
-virsh domifaddr --source lease $domain
-</pre>
-
- <p>
- If there's no record for either of the aforementioned commands, it's
- very likely that NSS module won't find anything and vice versa.
- As of <code>v3.0.0</code> libvirt provides
<code>libvirt_guest</code> NSS
- module that doesn't have this limitation. However, the statement is still
- true for the <code>libvirt</code> NSS module.
- </p>
- </body>
-</html>
diff --git a/docs/nss.rst b/docs/nss.rst
new file mode 100644
index 0000000000..8f98330221
--- /dev/null
+++ b/docs/nss.rst
@@ -0,0 +1,154 @@
+==================
+Libvirt NSS module
+==================
+
+.. contents::
+
+When it comes to managing guests and executing commands inside them, logging
+into guest operating system and doing the job is convenient. Users are used to
+ssh in this case. Ideally:
+
+``ssh user@virtualMachine``
+
+would be nice. But depending on virtual network configuration it might not be
+always possible. For instance, when using libvirt NATed network it's dnsmasq
+(spawned by libvirt) who assigns IP addresses to domains. But by default, the
+dnsmasq process is then not consulted when it comes to host name translation.
+Users work around this problem by configuring their libvirt network to assign
+static IP addresses and maintaining ``/etc/hosts`` file in sync. But this puts
+needless burden onto users. This is where NSS module comes handy.
+
+Installation
+------------
+
+Installing the module is really easy:
+
+::
+
+ # yum install libvirt-nss
+
+Configuration
+-------------
+
+Enabling the module is really easy. Just add **libvirt** into
+``/etc/nsswitch.conf`` file. For instance:
+
+::
+
+ $ cat /etc/nsswitch.conf
+ # /etc/nsswitch.conf:
+ passwd: compat
+ shadow: compat
+ group: compat
+ hosts: files libvirt dns
+ # ...
+
+So, in this specific case, whenever ssh program is looking up the host user is
+trying to connect to, **files** module is consulted first (which boils down to
+looking up the host name in ``/etc/hosts`` file), if not found **libvirt**
+module is consulted then. The DNS is the last effort then, if none of the
+previous modules matched the host in question. Therefore users should consider
+the order in which they want the modules to lookup given host name.
+
+Sources of information
+----------------------
+
+As of ``v3.0.0`` release, libvirt offers two NSS modules implementing two
+different methods of hostname translation. The first and older method is
+implemented by ``libvirt`` plugin and basically looks up the hostname to IP
+address translation in DHCP server records. Therefore this is dependent on
+hostname provided by guests. Thing is, not all the guests out there provide one
+in DHCP transactions, or not every sysadmin out there believes all the guests.
+Hence libvirt implements second method in ``libvirt_guest`` module which does
+libvirt guest name to IP address translation (regardless of hostname set in the
+guest).
+
+To enable either of the modules put their name into the ``nsswitch.conf`` file.
+For instance, to enable ``libvirt_guest`` module:
+
+::
+
+ $ cat /etc/nsswitch.conf
+ # /etc/nsswitch.conf:
+ hosts: files libvirt_guest dns
+ # ...
+
+Or users can enable both at the same time:
+
+::
+
+ $ cat /etc/nsswitch.conf
+ # /etc/nsswitch.conf:
+ hosts: files libvirt libvirt_guest dns
+ # ...
+
+This configuration will mean that if hostname is not found by the ``libvirt``
+module (e.g. because a guest did not sent hostname during DHCP transaction), the
+``libvirt_guest`` module is consulted (and if the hostname matches libvirt guest
+name it will be resolved).
+
+How does it work?
+-----------------
+
+Whenever an Unix process wants to do a host name translation
+`gethostbyname() <https://linux.die.net/man/3/gethostbyname>`__ or some variant
+of it is called. This is a glibc function that takes a string containing the
+host name, crunch it and produces a list of IP addresses assigned to that host.
+Now, glibc developers made a really good decision when implementing the
+internals of the function when they decided to make the function pluggable.
+Since there can be several sources for the records (e.g. ``/etc/hosts`` file,
+DNS, LDAP, etc.) it would not make much sense to create one big implementation
+containing all possible cases. What they have done instead is this pluggable
+mechanism. Small plugins implementing nothing but specific technology for lookup
+process are provided and the function then calls those plugins. There is just
+one configuration file that instructs the lookup function in which order should
+the plugins be called and which plugins should be loaded. For more info reading
+`wiki page <https://en.wikipedia.org/wiki/Name_Service_Switch>`__ is
+recommended.
+
+And this is point where libvirt comes in. Libvirt provides plugin for the NSS
+ecosystem. For some time now libvirt keeps a list of assigned IP addresses for
+libvirt networks. The NSS plugin does no more than search the list trying to
+find matching record for given host name. When found, matching IP address is
+returned to the caller. If not found, translation process continues with the
+next plugin configured. At this point it is important to stress the order in
+which plugins are called. Users should be aware that a hostname might match in
+multiple plugins and right after first match, translation process is terminated
+and no other plugin is consulted. Therefore, if there are two different records
+for the same host name users should carefully chose the lookup order.
+
+Limitations
+-----------
+
+#. The ``libvirt`` NSS module matches only hostnames provided by guest. If the
+ libvirt name and one advertised by guest differs, the latter is matched.
+ However, as of ``v3.0.0`` there are two libvirt NSS modules translating both
+ hostnames provided by guest and libvirt guest names.
+#. The module works only in that cases where IP addresses are assigned by
+ dnsmasq spawned by libvirt. Libvirt NATed networks are typical example.
+
+*The following paragraph describes implementation limitation of the ``libvirt``
+NSS module.* These limitation are result of libvirt's internal implementation.
+While libvirt can report IP addresses regardless of their origin, a public API
+must be used to obtain those. However, for the API a connection object is
+required. Doing that for every name translation request would be too costly.
+Fortunately, libvirt spawns dnsmasq for NATed networks. Not only that, it
+provides small executable that on each IP address space change updates an
+internal list of addresses thus keeping it in sync. The NSS module then merely
+consults the list trying to find the match. Users can view the list themselves:
+
+::
+
+ virsh net-dhcp-leases $network
+
+where ``$network`` iterates through all running networks. So the module does
+merely the same as
+
+::
+
+ virsh domifaddr --source lease $domain
+
+If there's no record for either of the aforementioned commands, it's very likely
+that NSS module won't find anything and vice versa. As of ``v3.0.0`` libvirt
+provides ``libvirt_guest`` NSS module that doesn't have this limitation.
+However, the statement is still true for the ``libvirt`` NSS module.
--
2.35.1