[pve-devel] [PATCH docs] pveproxy: improve LISTEN_IP doc

[Oguz Bektas]

On Wed, Apr 28, 2021 at 01:51:51PM +0200, Thomas Lamprecht wrote:
> On 28.04.21 13:42, Oguz Bektas wrote:
> >>> +
> >>> + LISTEN_IP="fe80::d8ee:34ff:fe37:4579%vmbr0"
> >>> +
> >>> +After the change you have to restart `pveproxy` for it to take effect:
> >>
> >> I'd specifically state that a reload is not enough and then add a small warning that
> >> a restart can stop some existing workers (not all, but e.g., shell connection is stopped
> >> and reconnected which may loose info on CTs without a screen/tmux instance running).
> >> Also, there's a short time window where no new connections are accepted IIRC (albeit
> >> I was the one fixing that for reload it's been to long since then, so not sure anymore)
> > 
> > i think the phrasing "you have to restart" already emphasizes this,
> > adding too many warnings or notes would just confuse users in my
> > opinion.
> 
> No, it's clear that something needs to be restarted, but "restart" is a general
> overused term which can mean lots of things (even reboot for some).
> 
> > 
> > though i don't see any harm in making the **restart** bold in that
> > sentence and adding that small warning about possible connection drop.
> 
> as said, restart is often used for the general semantic thing, be it reload or restart,
> so this is really not clear. 

why is it not clear? there's not a single instance of 'systemctl reload'
command in the documentation, and in instances where a service restart
is required, we specify 'systemctl restart' without any mention, e.g.,
in pvenode.adoc when setting up certificates)

so i don't see why users would imagine to 'reload' the service instead
of 'restart' when it's clearly written in bold, and the command is
right beneath the explanation...

> The gui also only triggers a reload, IIRC (pls. check)
> and thus "restarting" (it's named that way there) from there would not help.

yes, on the button it says "restart" but the tasklog says "reload".
so to me that sounds like a mislabeled button with wrong/lax use
of "restart" instead of the correct "reload".

> 
> You just need to write it in such a way that it is not confusing, then it is not
> a problem.

there's really nothing confusing IMO (besides the button). but if you
insist i will send another patch with the changes you recommended.

some possible alternative phrasing i'd suggest:

=====
After the change you have to **restart** `pveproxy` and `spiceproxy` for
it to take effect (**reload** or restart from GUI does not suffice):
 systemctl restart pveproxy spiceproxy
=====

or much simpler and less confusing:
=====
Run the following command to restart the proxy servers and apply the change:
 systemctl restart pveproxy spiceproxy
=====

with a note about the connection drop during restart.