From nobody Sun Feb 8 20:53:42 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927520; cv=none; d=zohomail.com; s=zohoarc; b=cg2n827cGnttrr0V6tyTgDpVCsRjOTlZWCvSKIYmzc7jaLDKJcaGnDQbRvgGSDRHVa650RuakCf+f7liHk10ruNDrPZEBbVoK8F0gQXnKV+Vgwo3oUHbukMo3VGh+i6tZvkR7BDI639kx/IDUMpYcRMhHSPGswScnKUsqHNFMGc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927520; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=vIQZSjr1ECT8h4/FdxEUs+F7elGMcA6rS/3bfa6p0go=; b=hxf3xdJBg/TVk5pI/FDfUiWKnZeC9jYXgFil9cWUCbuViqDH1cW0mjYtP9qRt5FXaSu86eiJ6q6SOIJMUib/UID7gLGsQAdtn5Lz+UZFu71uGp1WyEM4+z6Ls3eieE9tqxU+hR64k1isp3bzzHWLPKHGiaQIEHFtjZLTc3FEhPc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1646927520128119.34499387337394; Thu, 10 Mar 2022 07:52:00 -0800 (PST) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-632-YRm2J5qmOQK2QZRi318vHA-1; Thu, 10 Mar 2022 10:51:57 -0500 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6C1D22A59550; Thu, 10 Mar 2022 15:51:52 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 56E77C07F53; Thu, 10 Mar 2022 15:51:52 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 04B6A195FD6C; Thu, 10 Mar 2022 15:51:52 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B2725195FD43 for ; Thu, 10 Mar 2022 15:51:50 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 519AD7C02A; Thu, 10 Mar 2022 15:51:50 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8F8BB7C029 for ; Thu, 10 Mar 2022 15:51:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927519; h=from:from:sender:sender: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:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=vIQZSjr1ECT8h4/FdxEUs+F7elGMcA6rS/3bfa6p0go=; b=DsoastICygLCNWhrkOPV5yajHeuh7ngxQiqqmQ5bTvF1yCBfD0NYPYdi+taOYZlYiFtP+7 A6k1KIb+eGjaD7ea1OKmxTSwmXnobNxzGyz0ZoTEB7GsR5tpyt5IiZyojIruKVxae426ft BLjdA7aN7xKLGmyDFreO09u7ScbDUWk= X-MC-Unique: YRm2J5qmOQK2QZRi318vHA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 5/8] docs: Convert 'nss' page to rST Date: Thu, 10 Mar 2022 16:51:27 +0100 Message-Id: <3c82383069c29ce1bd6cfaa074ef7e49df4f7759.1646927156.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646928423748100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- docs/meson.build | 2 +- docs/nss.html.in | 189 ----------------------------------------------- docs/nss.rst | 154 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 155 insertions(+), 190 deletions(-) delete mode 100644 docs/nss.html.in create mode 100644 docs/nss.rst diff --git a/docs/meson.build b/docs/meson.build index 087afb15d9..3bdea1407d 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files =3D [ 'internals', 'java', 'logging', - 'nss', 'pci-hotplug', 'php', 'python', @@ -103,6 +102,7 @@ docs_rst_files =3D [ 'macos', 'migration', 'newreposetup', + 'nss', 'pci-addresses', 'platforms', 'programming-languages', diff --git a/docs/nss.html.in b/docs/nss.html.in deleted file mode 100644 index 5c58d1bd49..0000000000 --- a/docs/nss.html.in +++ /dev/null @@ -1,189 +0,0 @@ - - - - -

Libvirt NSS module

- -
    - -

    - When it comes to managing guests and executing commands inside them, l= ogging - into guest operating system and doing the job is convenient. Users are= used - to ssh in this case. Ideally: -

    - - ssh user@virtualMachine - -

    - would be nice. But depending on virtual network configuration it might= not - be always possible. For instance, when using libvirt NATed network it's - dnsmasq (spawned by libvirt) who assigns IP addresses to domains. But = by - default, the dnsmasq process is then not consulted when it comes to ho= st - name translation. Users work around this problem by configuring their - libvirt network to assign static IP addresses and maintaining - /etc/hosts file in sync. But this puts needless burden on= to - users. This is where NSS module comes handy. -

    - -

    Installation

    - -

    - Installing the module is really easy: -

    - -
    -# yum install libvirt-nss
-
    - -

    Configuration

    - -

    - Enabling the module is really easy. Just add libvirt into - /etc/nsswitch.conf file. For instance: -

    - -
    -$ 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= user - is trying to connect to, files module is consulted first (which - boils down 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 quest= ion. - Therefore users should consider the order in which they want the modul= es to - lookup given host name. -

    - -

    Sources of information

    - -

    - 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 serv= er - records. Therefore this is dependent on hostname provided by guests. T= hing - is, not all the guests out there provide one in DHCP transactions, or = not - every sysadmin out there believes all the guests. Hence libvirt implem= ents - second method in libvirt_guest module which does libvirt = guest - name to IP address translation (regardless of hostname set in the gues= t). -

    - -

    - To enable either of the modules put their name into the - nsswitch.conf file. For instance, to enable - libvirt_guest module: -

    - -
    -$ cat /etc/nsswitch.conf
-# /etc/nsswitch.conf:
-hosts:       files libvirt_guest dns
-# ...
-
    -

    Or users can enable both at the same time:

    -
    -$ 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 - libvirt 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 - gethostbyn= ame() - or some variant of it is called. This is a glibc function that takes a - string containing the host name, crunch it and produces a list of IP - addresses assigned to that host. Now, glibc developers made a really g= ood - decision when implementing the internals of the function when they dec= ided - to make the function pluggable. Since there can be several sources for= the - records (e.g. /etc/hosts file, DNS, LDAP, etc.) it would = not - make much sense to create one big implementation containing all possib= le - cases. What they have done instead is this pluggable mechanism. Small - plugins implementing nothing but specific technology for lookup proces= s are - provided and the function then calls those plugins. There is just 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 - reading = 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 searc= h the - list trying to find matching record for given host name. When found, - matching IP address is returned to the caller. If not found, translati= on - process continues with the next plugin configured. At this point it is - important to stress the order in which plugins are called. Users shoul= d be - aware that a hostname might match in multiple plugins and right after = first - match, translation process is terminated and no other plugin is consul= ted. - Therefore, if there are two different records for the same host name u= sers - should carefully chose the lookup order. -

    - -

    Limitations

    - -
      -
    1. The libvirt NSS module matches only hostnames provi= ded by guest. - If the libvirt name and one advertised by guest differs, the latte= r is - matched. However, as of v3.0.0 there are two libvirt = NSS modules - translating both hostnames provided by guest and libvirt guest nam= es.
      2. -
    2. The module works only in that cases where IP addresses are assig= ned by - dnsmasq spawned by libvirt. Libvirt NATed networks are typical - example.
      3. -
    - -

    - The following paragraph describes implementation limitation of the - libvirt NSS module. - These limitation are result of libvirt's internal implementation. While - libvirt can report IP addresses regardless of their origin, a public A= PI - 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 - costly. Fortunately, libvirt spawns dnsmasq for NATed networks. Not o= nly - 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 merely consults the list trying to find the match. Users c= an - view the list themselves: -

    - -
    -virsh net-dhcp-leases $network
-
    - -

    - where $network iterates through all running networks. So = the module - does merely the same as -

    - -
    -virsh domifaddr --source lease $domain
-
    - -

    - 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 libvirt provides libvirt_guest = NSS - module that doesn't have this limitation. However, the statement is st= ill - true for the libvirt NSS module. -

    - - diff --git a/docs/nss.rst b/docs/nss.rst new file mode 100644 index 0000000000..8f98330221 --- /dev/null +++ b/docs/nss.rst @@ -0,0 +1,154 @@ +=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 + +.. contents:: + +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: + +``ssh user@virtualMachine`` + +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. + +Installation +------------ + +Installing the module is really easy: + +:: + + # yum install libvirt-nss + +Configuration +------------- + +Enabling the module is really easy. Just add **libvirt** into +``/etc/nsswitch.conf`` file. For instance: + +:: + + $ 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 +---------------------- + +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). + +To enable either of the modules put their name into the ``nsswitch.conf`` = file. +For instance, to enable ``libvirt_guest`` module: + +:: + + $ cat /etc/nsswitch.conf + # /etc/nsswitch.conf: + hosts: files libvirt_guest dns + # ... + +Or users can enable both at the same time: + +:: + + $ 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. + +Limitations +----------- + +#. 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: + +:: + + virsh net-dhcp-leases $network + +where ``$network`` iterates through all running networks. So the module do= es +merely the same as + +:: + + virsh domifaddr --source lease $domain + +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. --=20 2.35.1