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@xxxxxxxxxx> --- 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>gethostbyname()</code></a> + 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 -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list