diff --git a/cfg.mk b/cfg.mk index f5573dbd63..8e8586f611 100644 --- a/cfg.mk +++ b/cfg.mk @@ -1193,6 +1193,8 @@ exclude_file_name_regexp--sc_prohibit_strncpy = ^src/util/virstring\.c$$ exclude_file_name_regexp--sc_prohibit_strtol = ^examples/dom.*/.*\.c$$ +exclude_file_name_regexp--sc_prohibit_gethostby = ^docs/nss.html.in$$ + exclude_file_name_regexp--sc_prohibit_xmlGetProp = ^src/util/virxml\.c$$ exclude_file_name_regexp--sc_prohibit_xmlURI = ^src/util/viruri\.c$$ diff --git a/docs/nss.html.in b/docs/nss.html.in new file mode 100644 index 0000000000..84ea8df6db --- /dev/null +++ b/docs/nss.html.in @@ -0,0 +1,141 @@ + + + + +

Libvirt NSS module

+ + + +

+ 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. +

+ +

How does it work?

+ +

+ Whenever an Unix process wants to do a host name translation + 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 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

+ +
    +
  1. The libvirt NSS module matches only hostnames provided by guest. If + the libvirt name and one advertised by guest differs, the latter is + matched.
    2. +
  2. The module works only in that cases where IP addresses are assigned by + dnsmasq spawned by libvirt. Libvirt NATed networks are typical + example.
    3. +
+ +

+ 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. +

+ + diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in index 7e3746eee8..22e410c964 100644 --- a/docs/sitemap.html.in +++ b/docs/sitemap.html.in @@ -120,6 +120,10 @@ Hooks Hooks for system specific management +
  • + NSS module + Enable domain host name translation to IP addresses +