On 11/13/24 11:35, Andrea Bolognani wrote: > 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@xxxxxxxxxx> > --- > 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. syntax check is not happy with this style of linking: libvirt.git/docs/nss.rst:22:`limitations <#limitations>`__ section for more information. libvirt.git/docs/nss.rst:50:(see `below <#variants>`_ for differences between the two) will be used make: Leaving directory 'libvirt.git/_build/build-aux' stderr: use local reference within a file make: *** [libvirt.git/build-aux/syntax-check.mk:1136: sc_avoid_remote_reference_to_local_file] Error 1 > > Installation > ------------ > > -Installing the module is really easy: > +Installing the module on Fedora or RHEL is really easy: Since you're changing this to RHEL/Fedora specifically .. > > :: > > # yum install libvirt-nss .. I'd also s/yum/dnf/ Otherwise the change looks good. Michal