mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 21:55:25 +00:00
b3a4b049c4
When using recent Fedora and RHEL versions, the manual setup that is otherwise necessary to enable the module can be replaced with executing a single command. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
120 lines
4.0 KiB
ReStructuredText
120 lines
4.0 KiB
ReStructuredText
.. 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 <variants_>`__ 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() <https://linux.die.net/man/3/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 <https://en.wikipedia.org/wiki/Name_Service_Switch>`__ 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 <ssh-proxy.html>`__.
|
|
This allows the use of SSH even for guests that have no network connectivity,
|
|
by communicating over VSOCK.
|