libvirt: Libvirt NSS module
Libvirt NSS module
Contents
Installation
Configuration
Variants
Implementation details
Limitations
Debugging
Alternatives
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.
Debugging
Since 11.6.0
both NSS modules check for
LIBVIRT_NSS_DEBUG
environment variable¸ which if set to any value turns on printing of debug and
error messages onto standard error output. This can be useful when debugging
either of the module.
$ LIBVIRT_NSS_DEBUG=1 getent hosts mydomain
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.
Contribute
Docs
Website
(via DuckDuckGo)
Wiki
(via DuckDuckGo)
Developers list
Users list
Contact
email
irc
Community
fosstodon
stackoverflow
serverfault
Contribute
edit this page
Participants in the libvirt project agree to abide by
the project code of conduct