libvirt/docs/nss.rst

Libvirt NSS module

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