1:21 p.m.
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>
---
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