Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/meson.build | 2 +- docs/nss.html.in | 189 ----------------------------------------------- docs/nss.rst | 154 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 155 insertions(+), 190 deletions(-) delete mode 100644 docs/nss.html.in create mode 100644 docs/nss.rst diff --git a/docs/meson.build b/docs/meson.build index 087afb15d9..3bdea1407d 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files = [ 'internals', 'java', 'logging', - 'nss', 'pci-hotplug', 'php', 'python', @@ -103,6 +102,7 @@ docs_rst_files = [ 'macos', 'migration', 'newreposetup', + 'nss', 'pci-addresses', 'platforms', 'programming-languages', diff --git a/docs/nss.html.in b/docs/nss.html.in deleted file mode 100644 index 5c58d1bd49..0000000000 --- a/docs/nss.html.in +++ /dev/null @@ -1,189 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<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 id="Installation">Installation</a></h2> - - <p> - Installing the module is really easy: - </p> - -<pre> -# yum install libvirt-nss -</pre> - - <h2><a id="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 id="Sources">Sources of information</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></h2> - - <p> - Whenever an Unix process wants to do a host name translation - <a href="https://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></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> - </body> -</html> diff --git a/docs/nss.rst b/docs/nss.rst new file mode 100644 index 0000000000..8f98330221 --- /dev/null +++ b/docs/nss.rst @@ -0,0 +1,154 @@ +================== +Libvirt NSS module +================== + +.. contents:: + +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: + +``ssh user@virtualMachine`` + +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 ``/etc/hosts`` file in sync. But this puts +needless burden onto users. This is where NSS module comes handy. + +Installation +------------ + +Installing the module is really easy: + +:: + + # yum install libvirt-nss + +Configuration +------------- + +Enabling the module is really easy. Just add **libvirt** into +``/etc/nsswitch.conf`` file. For instance: + +:: + + $ cat /etc/nsswitch.conf + # /etc/nsswitch.conf: + passwd: compat + shadow: compat + group: compat + hosts: files libvirt dns + # ... + +So, in this specific case, whenever ssh program is looking up the host user is +trying to connect to, **files** module is consulted first (which boils down to +looking up the host name in ``/etc/hosts`` file), if not found **libvirt** +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. + +Sources of information +---------------------- + +As of ``v3.0.0`` release, libvirt offers two NSS modules implementing two +different methods of hostname translation. The first and older method is +implemented by ``libvirt`` 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 ``libvirt_guest`` module which does +libvirt guest name to IP address translation (regardless of hostname set in the +guest). + +To enable either of the modules put their name into the ``nsswitch.conf`` file. +For instance, to enable ``libvirt_guest`` module: + +:: + + $ cat /etc/nsswitch.conf + # /etc/nsswitch.conf: + hosts: files libvirt_guest dns + # ... + +Or users can enable both at the same time: + +:: + + $ cat /etc/nsswitch.conf + # /etc/nsswitch.conf: + hosts: files libvirt libvirt_guest dns + # ... + +This configuration will mean that if hostname is not found by the ``libvirt`` +module (e.g. because a guest did not sent hostname during DHCP transaction), the +``libvirt_guest`` module is consulted (and if the hostname matches libvirt guest +name it will be resolved). + +How does it work? +----------------- + +Whenever an Unix process wants to do a host name translation +`gethostbyname() <https://linux.die.net/man/3/gethostbyname>`__ 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. ``/etc/hosts`` 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 +`wiki page <https://en.wikipedia.org/wiki/Name_Service_Switch>`__ is +recommended. + +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. + +Limitations +----------- + +#. The ``libvirt`` 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 ``v3.0.0`` there are two libvirt NSS modules translating both + hostnames provided by guest and libvirt guest names. +#. The module works only in that cases where IP addresses are assigned by + dnsmasq spawned by libvirt. Libvirt NATed networks are typical example. + +*The following paragraph describes implementation limitation of the ``libvirt`` +NSS module.* 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: + +:: + + virsh net-dhcp-leases $network + +where ``$network`` iterates through all running networks. So the module does +merely the same as + +:: + + virsh domifaddr --source lease $domain + +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 ``v3.0.0`` libvirt +provides ``libvirt_guest`` NSS module that doesn't have this limitation. +However, the statement is still true for the ``libvirt`` NSS module. -- 2.35.1
