From nobody Thu Nov 21 17:15:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1731494307439100.79937447081875; Wed, 13 Nov 2024 02:38:27 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id 6997F16F8; Wed, 13 Nov 2024 05:38:26 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 839F1192E; Wed, 13 Nov 2024 05:37:17 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id 3A002180F; Wed, 13 Nov 2024 05:37:13 -0500 (EST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 1D8251746 for ; Wed, 13 Nov 2024 05:36:01 -0500 (EST) Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-563-bxZC4SkvO7yocZvtT2-Zxw-1; Wed, 13 Nov 2024 05:35:59 -0500 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 43442195604F for ; Wed, 13 Nov 2024 10:35:58 +0000 (UTC) Received: from harajuku.usersys.redhat.com.homenet.telecomitalia.it (unknown [10.45.225.210]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 63B7D30000DF for ; Wed, 13 Nov 2024 10:35:57 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-1.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1731494160; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=8Uuo3N1d++VsXYgkjpLUZfX1XZ98X95vhF/+yacEXaw=; b=UumDhIh2UVbHbJXBfwjFwtr9wORF2e3iHt4AhC59W9wFRty2vnhjn3CQpQaVbzpRRcaJ6z EFTjlNtUU+r9xxgWOL9Ui8/gHvzdwEqUrb8IeI8ycNnEPzIJD/J5fa/ncYingQ2XGgPHW4 zE+Fezud1320606H/BUK2jjLHRxhxqs= X-MC-Unique: bxZC4SkvO7yocZvtT2-Zxw-1 X-Mimecast-MFC-AGG-ID: bxZC4SkvO7yocZvtT2-Zxw From: Andrea Bolognani To: devel@lists.libvirt.org Subject: [PATCH 1/2] docs: Rework documentation for the NSS module Date: Wed, 13 Nov 2024 11:35:52 +0100 Message-ID: <20241113103553.257800-2-abologna@redhat.com> In-Reply-To: <20241113103553.257800-1-abologna@redhat.com> References: <20241113103553.257800-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: -_upIAHg-NRlO0I7JhlXCbWqBVYq9YDkZ8tSYbafer4_1731494158 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: P2OUUTGDFCBNE2KGGWJI7TCXGHPHZ3FD X-Message-ID-Hash: P2OUUTGDFCBNE2KGGWJI7TCXGHPHZ3FD X-MailFrom: abologna@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1731494309173116600 Content-Type: text/plain; charset="utf-8"; x-default="true" The page contains some confusing information, especially around limitations that supposedly only affect one of the two variants, and goes into what is arguably an unnecessary amount of detail when it comes to its inner workings. We can make the page a lot shorter and snappier without affecting its usefulness, so let's do just that. Signed-off-by: Andrea Bolognani --- docs/nss.rst | 189 +++++++++++++++++++-------------------------------- 1 file changed, 70 insertions(+), 119 deletions(-) diff --git a/docs/nss.rst b/docs/nss.rst index 53955a3278..eeb48ea1f2 100644 --- a/docs/nss.rst +++ b/docs/nss.rst @@ -1,161 +1,112 @@ +.. role:: since + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Libvirt NSS module =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 .. contents:: =20 -When it comes to managing guests and executing commands inside them, loggi= ng -into guest operating system and doing the job is convenient. Users are use= d to -ssh in this case. Ideally: +Effectively managing guests often requires connecting to them via SSH, sam= e as +you would for any remote machine. Ideally + +:: + + $ ssh user@mydomain =20 -``ssh user@virtualMachine`` +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. =20 -would be nice. But depending on virtual network configuration it might not= be -always possible. For instance, when using libvirt NATed network it's dnsma= sq -(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 translati= on. -Users work around this problem by configuring their libvirt network to ass= ign -static IP addresses and maintaining ``/etc/hosts`` file in sync. But this = puts -needless burden onto users. This is where NSS module comes handy. +Note that this feature only works in certain scenarios. See the +`limitations <#limitations>`__ section for more information. =20 Installation ------------ =20 -Installing the module is really easy: +Installing the module on Fedora or RHEL is really easy: =20 :: =20 # yum install libvirt-nss =20 +The package might have a different name on other distributions, but the pr= ocess +of installing it will be similar. + Configuration ------------- =20 -Enabling the module is really easy. Just add **libvirt** into -``/etc/nsswitch.conf`` file. For instance: +To enable the module, modify ``/etc/nsswitch.conf`` so that the ``hosts`` = line +looks similar to =20 :: =20 - $ 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 use= r is -trying to connect to, **files** module is consulted first (which boils dow= n 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 cons= ider -the order in which they want the modules to lookup given host name. - -Sources of information ----------------------- + hosts: files libvirt libvirt_guest dns =20 -As of ``v3.0.0`` release, libvirt offers two NSS modules implementing two -different methods of hostname translation. The first and older method is -implemented by ``libvirt`` plugin and basically looks up the hostname to IP -address translation in DHCP server records. Therefore this is dependent on -hostname provided by guests. Thing is, not all the guests out there provid= e one -in DHCP transactions, or not every sysadmin out there believes all the gue= sts. -Hence libvirt implements second method in ``libvirt_guest`` module which d= oes -libvirt guest name to IP address translation (regardless of hostname set i= n the -guest). +With this configuration, whenever SSH (or any other application) +tries to contact a guest, the ``files`` module will be consulted first (th= is +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`` mod= ules +(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. =20 -To enable either of the modules put their name into the ``nsswitch.conf`` = file. -For instance, to enable ``libvirt_guest`` module: +Variants +-------- =20 -:: +There are two different variants of the module: =20 - $ cat /etc/nsswitch.conf - # /etc/nsswitch.conf: - hosts: files libvirt_guest dns - # ... +* ``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 f= ully + configured yet; =20 -Or users can enable both at the same time: +* ``libvirt_guest`` (:since:`since 3.0.0`) resolves hostnames by mapping t= hem + directly to libvirt domain names, so it will work regardless of how the = guest + OS is configured and will have more predictable results. =20 -:: +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 lis= ted. =20 - $ cat /etc/nsswitch.conf - # /etc/nsswitch.conf: - hosts: files libvirt libvirt_guest dns - # ... - -This configuration will mean that if hostname is not found by the ``libvir= t`` -module (e.g. because a guest did not sent hostname during DHCP transaction= ), the -``libvirt_guest`` module is consulted (and if the hostname matches libvirt= guest -name it will be resolved). - -How does it work? ------------------ - -Whenever an Unix process wants to do a host name translation -`gethostbyname() `__ or some va= riant -of it is called. This is a glibc function that takes a string containing t= he -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`` fi= le, -DNS, LDAP, etc.) it would not make much sense to create one big implementa= tion -containing all possible cases. What they have done instead is this pluggab= le -mechanism. Small plugins implementing nothing but specific technology for = lookup -process are provided and the function then calls those plugins. There is j= ust -one configuration file that instructs the lookup function in which order s= hould -the plugins be called and which plugins should be loaded. For more info re= ading -`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 t= he -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 matc= h in -multiple plugins and right after first match, translation process is termi= nated -and no other plugin is consulted. Therefore, if there are two different re= cords -for the same host name users should carefully chose the lookup order. +Implementation details +---------------------- =20 -Limitations ------------ +Whenever a Unix process needs to convert a hostname into an IP address, it= will +call the `gethostbyname() `__ l= ibc +function or one of its variants. =20 -#. The ``libvirt`` NSS module matches only hostnames provided by guest. If= the - libvirt name and one advertised by guest differs, the latter is matched. - However, as of ``v3.0.0`` there are two libvirt NSS modules translating= both - hostnames provided by guest and libvirt guest names. -#. The module works only in that cases where IP addresses are assigned by - dnsmasq spawned by libvirt. Libvirt NATed networks are typical example. - -*The following paragraph describes implementation limitation of the ``libv= irt`` -NSS module.* These limitation are result of libvirt's internal implementat= ion. -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 costl= y. -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 me= rely -consults the list trying to find the match. Users can view the list themse= lves: +Since multiple sources for this information are possible (for example the +contents of ``/etc/hosts``, DNS, LDAP, etc.) a mechanism called +`NSS `__ has been creat= ed 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. =20 -:: +In the case of libvirt, the lookup is performed by inspecting the DHCP lea= ses +handed out by ``dnsmasq``, the software used to implement NATed networks. = The +results will be the same that would be reported by =20 - virsh net-dhcp-leases $network +:: =20 -where ``$network`` iterates through all running networks. So the module do= es -merely the same as + $ virsh domifaddr --source lease mydomain =20 -:: +except that things will work transparently for any application that uses t= he +libc resolver, without it needing to link against libvirt or even be aware= of +its existence. =20 - virsh domifaddr --source lease $domain +Limitations +----------- =20 -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. As of ``v3.0.0`` libvi= rt -provides ``libvirt_guest`` NSS module that doesn't have this limitation. -However, the statement is still true for the ``libvirt`` NSS module. +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 obta= in +their IP addresses in any other way (usermode networking, assigned network +devices and so on) will not be able to have their hostnames resolved throu= gh +it. =20 Alternatives ------------ =20 -As of ``v10.3.0`` libvirt implements an `SSH proxy `__ whi= ch -doesn't require any network interface to SSH into the guest as SSH flows -through a VSOCK device. +:since:`Since 10.3.0`, libvirt implements an `SSH proxy `_= _. +This allows the use of SSH even for guests that have no network connectivi= ty, +by communicating over VSOCK. --=20 2.47.0