[libvirt] [PATCH] docs: Document NSS module

Tuesday, 29 March 2016

While we have a wiki page describing the feature [1] since the
feature is distributed in our .tar.gz we ought to document it. So
I went ahead, copied the wiki page and reformatted so it fits our
docs coding style.

1: http://wiki.libvirt.org/page/NSS_module

Signed-off-by: Michal Privoznik <mprivozn(a)redhat.com&gt;
---
 docs/nss.html.in     | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/sitemap.html.in |   4 ++
 2 files changed, 145 insertions(+)
 create mode 100644 docs/nss.html.in

diff --git a/docs/nss.html.in b/docs/nss.html.in
new file mode 100644
index 0000000..84ea8df
--- /dev/null
+++ b/docs/nss.html.in
@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<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 name="Installation">Installation</a></h2>
+
+    <p>
+    Installing the module is really easy:
+    </p>
+
+<pre>
+# yum install libvirt-nss
+</pre>
+
+    <h2><a name="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 name="Internals">How does it work?</a></h2>
+
+    <p>
+    Whenever an Unix process wants to do a host name translation
+    <a
href="http://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 name="Limitations">Limitations</a></h2>
+
+    <ol>
+      <li>The libvirt NSS module matches only hostnames provided by guest. If
+        the libvirt name and one advertised by guest differs, the latter is
+        matched.</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>
+    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.
+    </p>
+  </body>
+</html>
diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in
index 7e3746e..22e410c 100644
--- a/docs/sitemap.html.in
+++ b/docs/sitemap.html.in
@@ -120,6 +120,10 @@
                 <a href="hooks.html">Hooks</a>
                 <span>Hooks for system specific management</span>
               </li>
+              <li>
+                <a href="nss.html">NSS module</a>
+                <span>Enable domain host name translation to IP
addresses</span>
+              </li>
             </ul>
           </li>
           <li>
-- 
2.7.3


    

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005