Re: [PATCH 1/2] docs: Rework documentation for the NSS module

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 <abologna(a)redhat.com&gt; --- 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 + ================== Libvirt NSS module ================== .. contents:: -When it comes to managing guests and executing commands inside them, logging -into guest operating system and doing the job is convenient. Users are used to -ssh in this case. Ideally: +Effectively managing guests often requires connecting to them via SSH, same as +you would for any remote machine. Ideally + +:: + + $ ssh user@mydomain -``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. -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 host 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 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.

Installation ------------ -Installing the module is really easy: +Installing the module on Fedora or RHEL is really easy:

:: # yum install libvirt-nss