docs/nss.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Libvirt NSS module</h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <p>
  10     When it comes to managing guests and executing commands inside them, logging
  11     into guest operating system and doing the job is convenient. Users are used
  12     to ssh in this case. Ideally:
  13     </p>
  14
  15     <code>ssh user@virtualMachine</code>
  16
  17     <p>
  18     would be nice. But depending on virtual network configuration it might not
  19     be always possible. For instance, when using libvirt NATed network it's
  20     dnsmasq (spawned by libvirt) who assigns IP addresses to domains. But by
  21     default, the dnsmasq process is then not consulted when it comes to host
  22     name translation.  Users work around this problem by configuring their
  23     libvirt network to assign static IP addresses and maintaining
  24     <code>/etc/hosts</code> file in sync. But this puts needless burden onto
  25     users. This is where NSS module comes handy.
  26     </p>
  27
  28     <h2><a id="Installation">Installation</a></h2>
  29
  30     <p>
  31     Installing the module is really easy:
  32     </p>
  33
  34 <pre>
  35 # yum install libvirt-nss
  36 </pre>
  37
  38     <h2><a id="Configuration">Configuration</a></h2>
  39
  40     <p>
  41     Enabling the module is really easy. Just add <b>libvirt</b> into
  42     <code>/etc/nsswitch.conf</code> file. For instance:
  43     </p>
  44
  45 <pre>
  46 $ cat /etc/nsswitch.conf
  47 # /etc/nsswitch.conf:
  48 passwd:      compat
  49 shadow:      compat
  50 group:       compat
  51 hosts:       files libvirt dns
  52 # ...
  53 </pre>
  54
  55     <p>
  56     So, in this specific case, whenever ssh program is looking up the host user
  57     is trying to connect to, <b>files</b> module is consulted first (which
  58     boils down to looking up the host name in <code>/etc/hosts</code> file), if
  59     not found <b>libvirt</b> module is consulted then. The DNS is the last
  60     effort then, if none of the previous modules matched the host in question.
  61     Therefore users should consider the order in which they want the modules to
  62     lookup given host name.
  63     </p>
  64
  65     <h2><a id="Sources">Sources of information</a></h2>
  66
  67     <p>
  68     As of <code>v3.0.0</code> release, libvirt offers two NSS modules
  69     implementing two different methods of hostname translation. The first and
  70     older method is implemented by <code>libvirt</code> plugin and
  71     basically looks up the hostname to IP address translation in DHCP server
  72     records. Therefore this is dependent on hostname provided by guests. Thing
  73     is, not all the guests out there provide one in DHCP transactions, or not
  74     every sysadmin out there believes all the guests. Hence libvirt implements
  75     second method in <code>libvirt_guest</code> module which does libvirt guest
  76     name to IP address translation (regardless of hostname set in the guest).
  77     </p>
  78
  79     <p>
  80     To enable either of the modules put their name into the
  81     <code>nsswitch.conf</code> file. For instance, to enable
  82     <code>libvirt_guest</code> module:
  83     </p>
  84
  85 <pre>
  86 $ cat /etc/nsswitch.conf
  87 # /etc/nsswitch.conf:
  88 hosts:       files libvirt_guest dns
  89 # ...
  90 </pre>
  91     <p>Or users can enable both at the same time:</p>
  92 <pre>
  93 $ cat /etc/nsswitch.conf
  94 # /etc/nsswitch.conf:
  95 hosts:       files libvirt libvirt_guest dns
  96 # ...
  97 </pre>
  98
  99     <p>
 100     This configuration will mean that if hostname is not found by the
 101     <code>libvirt</code> module (e.g. because a guest did not sent hostname
 102     during DHCP transaction), the <code>libvirt_guest</code> module is
 103     consulted (and if the hostname matches libvirt guest name it will be
 104     resolved).
 105     </p>
 106
 107     <h2><a id="Internals">How does it work?</a></h2>
 108
 109     <p>
 110     Whenever an Unix process wants to do a host name translation
 111     <a href="http://linux.die.net/man/3/gethostbyname"><code>gethostbyname()</code></a>
 112     or some variant of it is called. This is a glibc function that takes a
 113     string containing the host name, crunch it and produces a list of IP
 114     addresses assigned to that host. Now, glibc developers made a really good
 115     decision when implementing the internals of the function when they decided
 116     to make the function pluggable. Since there can be several sources for the
 117     records (e.g. <code>/etc/hosts</code> file, DNS, LDAP, etc.) it would not
 118     make much sense to create one big implementation containing all possible
 119     cases. What they have done instead is this pluggable mechanism. Small
 120     plugins implementing nothing but specific technology for lookup process are
 121     provided and the function then calls those plugins. There is just one
 122     configuration file that instructs the lookup function in which order should
 123     the plugins be called and which plugins should be loaded. For more info
 124     reading <a href="https://en.wikipedia.org/wiki/Name_Service_Switch">wiki
 125     page</a> is recommended.
 126     </p>
 127
 128     <p>
 129     And this is point where libvirt comes in. Libvirt provides plugin for the
 130     NSS ecosystem. For some time now libvirt keeps a list of assigned IP
 131     addresses for libvirt networks. The NSS plugin does no more than search the
 132     list trying to find matching record for given host name. When found,
 133     matching IP address is returned to the caller. If not found, translation
 134     process continues with the next plugin configured. At this point it is
 135     important to stress the order in which plugins are called. Users should be
 136     aware that a hostname might match in multiple plugins and right after first
 137     match, translation process is terminated and no other plugin is consulted.
 138     Therefore, if there are two different records for the same host name users
 139     should carefully chose the lookup order.
 140     </p>
 141
 142     <h2><a id="Limitations">Limitations</a></h2>
 143
 144     <ol>
 145       <li>The <code>libvirt</code> NSS module matches only hostnames provided by guest.
 146         If the libvirt name and one advertised by guest differs, the latter is
 147         matched. However, as of <code>v3.0.0</code> there are two libvirt NSS modules
 148         translating both hostnames provided by guest and libvirt guest names.</li>
 149       <li>The module works only in that cases where IP addresses are assigned by
 150         dnsmasq spawned by libvirt. Libvirt NATed networks are typical
 151         example.</li>
 152     </ol>
 153
 154     <p>
 155     <i>The following paragraph describes implementation limitation of the
 156     <code>libvirt</code> NSS module.</i>
 157     These limitation are result of libvirt's internal implementation. While
 158     libvirt can report IP addresses regardless of their origin, a public API
 159     must be used to obtain those. However, for the API a connection object is
 160     required. Doing that for every name translation request would be too
 161     costly.  Fortunately, libvirt spawns dnsmasq for NATed networks. Not only
 162     that, it provides small executable that on each IP address space change
 163     updates an internal list of addresses thus keeping it in sync. The NSS
 164     module then merely consults the list trying to find the match. Users can
 165     view the list themselves:
 166     </p>
 167
 168 <pre>
 169 virsh net-dhcp-leases $network
 170 </pre>
 171
 172     <p>
 173     where <code>$network</code> iterates through all running networks. So the module
 174     does merely the same as
 175     </p>
 176
 177 <pre>
 178 virsh domifaddr --source lease $domain
 179 </pre>
 180
 181     <p>
 182     If there's no record for either of the aforementioned commands, it's
 183     very likely that NSS module won't find anything and vice versa.
 184     As of <code>v3.0.0</code> libvirt provides <code>libvirt_guest</code> NSS
 185     module that doesn't have this limitation. However, the statement is still
 186     true for the <code>libvirt</code> NSS module.
 187     </p>
 188   </body>
 189 </html>