<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<!--
This file is autogenerated from nss.html.in
Do not edit this file. Changes will be lost.
-->
<!--
This page was generated at Tue Aug 29 08:42:58 UTC 2017.
-->
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="stylesheet" type="text/css" href="main.css"/>
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"/>
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/>
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/>
<link rel="manifest" href="/manifest.json"/>
<meta name="theme-color" content="#ffffff"/>
<title>libvirt: Libvirt NSS module</title>
<meta name="description" content="libvirt, virtualization, virtualization API"/>
<script type="text/javascript">
<!--
function init() {
window.addEventListener('scroll', function(e){
var distanceY = window.pageYOffset || document.documentElement.scrollTop,
shrinkOn = 94
home = document.getElementById("home");
links = document.getElementById("jumplinks");
search = document.getElementById("search");
body = document.getElementById("body");
if (distanceY > shrinkOn) {
if (home.className != "navhide") {
body.className = "navhide"
home.className = "navhide"
links.className = "navhide"
search.className = "navhide"
}
} else {
if (home.className == "navhide") {
body.className = ""
home.className = ""
links.className = ""
search.className = ""
}
}
});
}
window.onload = init();
-->
</script>
</head>
<body>
<div id="body">
<div id="content">
<h1>Libvirt NSS module</h1>
<ul>
<li>
<a href="#Installation">Installation</a>
</li>
<li>
<a href="#Configuration">Configuration</a>
</li>
<li>
<a href="#Sources">Sources of information</a>
</li>
<li>
<a href="#Internals">How does it work?</a>
</li>
<li>
<a href="#Limitations">Limitations</a>
</li>
</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>
<a class="headerlink" href="#Installation" title="Permalink to this headline">¶</a>
</h2>
<p>
Installing the module is really easy:
</p>
<pre>
# yum install libvirt-nss
</pre>
<h2>
<a id="Configuration">Configuration</a>
<a class="headerlink" href="#Configuration" title="Permalink to this headline">¶</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>
<a class="headerlink" href="#Sources" title="Permalink to this headline">¶</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>
<a class="headerlink" href="#Internals" title="Permalink to this headline">¶</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 id="Limitations">Limitations</a>
<a class="headerlink" href="#Limitations" title="Permalink to this headline">¶</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>
</div>
</div>
<div id="nav">
<div id="home">
<a href="index.html">Home</a>
</div>
<div id="jumplinks">
<ul>
<li>
<a href="downloads.html">Download</a>
</li>
<li>
<a href="contribute.html">Contribute</a>
</li>
<li>
<a href="docs.html">Docs</a>
</li>
</ul>
</div>
<div id="search">
<form action="search.php" enctype="application/x-www-form-urlencoded" method="get">
<div>
<input name="query" type="text" size="12" value=""/>
<input name="submit" type="submit" value="Go"/>
</div>
</form>
</div>
</div>
<div id="footer">
<div id="contact">
<h3>Contact</h3>
<ul>
<li>
<a href="contact.html#email">email</a>
</li>
<li>
<a href="contact.html#irc">irc</a>
</li>
</ul>
</div>
<div id="community">
<h3>Community</h3>
<ul>
<li>
<a href="https://twitter.com/hashtag/libvirt">twitter</a>
</li>
<li>
<a href="https://plus.google.com/communities/109522598353007505282">google+</a>
</li>
<li>
<a href="http://stackoverflow.com/questions/tagged/libvirt">stackoverflow</a>
</li>
<li>
<a href="http://serverfault.com/questions/tagged/libvirt">serverfault</a>
</li>
</ul>
</div>
<div id="conduct">
Participants in the libvirt project agree to abide by <a href="governance.html#codeofconduct">the project code of conduct</a></div>
<br class="clear"/>
</div>
</body>
</html>
