.. role:: since ================== Libvirt NSS module ================== .. contents:: Effectively managing guests often requires connecting to them via SSH, same as you would for any remote machine. Ideally :: $ ssh user@mydomain would work out of the box, but depending on the network configuration that might not be the case. Setting up the libvirt NSS module is a one-time operation that makes the process of connecting from the host to the guests running on it much more convenient. Note that this feature only works in certain scenarios. See the `limitations`_ section for more information. Installation ------------ Installing the module on Fedora or RHEL is really easy: :: # dnf install libvirt-nss The package might have a different name on other distributions, but the process of installing it will be similar. Configuration ------------- If you're running a new enough version of Fedora (>= 37) or RHEL (>= 10), then you can use ``authselect`` to enable the module with a single command: :: # authselect enable-feature with-libvirt For other distributions, you will have to manually update the configuration in ``/etc/nsswitch.conf`` so that the ``hosts`` line looks similar to :: hosts: files libvirt libvirt_guest dns With this configuration, whenever SSH (or any other application) tries to contact a guest, the ``files`` module will be consulted first (this boils down to searching for a matching line in ``/etc/hosts``); if no IP address could be found that way, the ``libvirt`` and ``libvirt_guest`` modules (see `below `__ for differences between the two) will be used instead. Finally, if no previous attempt at resolving the hostname was successful, a DNS query will be performed. Variants -------- There are two different variants of the module: * ``libvirt`` (:since:`since 1.3.3`) resolves hostnames based on the information that the guest OS itself has reported to the DHCP server when asking for an IP address, so it won't work if the guest OS hasn't been fully configured yet; * ``libvirt_guest`` (:since:`since 3.0.0`) resolves hostnames by mapping them directly to libvirt domain names, so it will work regardless of how the guest OS is configured and will have more predictable results. The recommended configuration seen above enables both of them and gives priority to the former but it's also possible to enable only a single one, or to alter the precedence by simply changing the order in which they are listed. Implementation details ---------------------- Whenever a Unix process needs to convert a hostname into an IP address, it will call the `gethostbyname() `__ libc function or one of its variants. Since multiple sources for this information are possible (for example the contents of ``/etc/hosts``, DNS, LDAP, etc.) a mechanism called `NSS `__ has been created to make the name resolution process extensible. This allows each source to be implemented as a separate plugin that can be enabled or disabled based on the administrator's preferences. In the case of libvirt, the lookup is performed by inspecting the DHCP leases handed out by ``dnsmasq``, the software used to implement NATed networks. The results will be the same that would be reported by :: $ virsh domifaddr --source lease mydomain except that things will work transparently for any application that uses the libc resolver, without it needing to link against libvirt or even be aware of its existence. Limitations ----------- Since the libvirt NSS module works by looking at ``dnsmasq``, it can only work for guests that are connected to a NATed libvirt network. Guests that obtain their IP addresses in any other way (usermode networking, assigned network devices and so on) will not be able to have their hostnames resolved through it. Alternatives ------------ :since:`Since 10.3.0`, libvirt implements an `SSH proxy `__. This allows the use of SSH even for guests that have no network connectivity, by communicating over VSOCK.