bin/57736: rtsold(8) compat man page is both imprecise and unhelpful

[he%NetBSD.org@localhost]

>Number:         57736
>Category:       bin
>Synopsis:       rtsold(8) compat man page is both imprecise and unhelpful
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Nov 30 09:10:00 +0000 2023
>Originator:     he%NetBSD.org@localhost
>Release:        NetBSD 10.0_BETA
>Organization:
	I Try...
>Environment:
System: NetBSD smistad.uninett.no 10.0_BETA NetBSD 10.0_BETA (GENERIC) #5: Thu Jan 12 20:52:28 CET 2023 he%smistad.uninett.no@localhost:/usr/obj/sys/arch/amd64/compile/GENERIC amd64
Architecture: x86_64
Machine: amd64
>Description:

	Several issues with the man page as it stands
	(inspected/verified via https://man.netbsd.org/):

	1. It is not supplying information which provides a good
  	   replacement for the old "rtsol" command.  The old "rtsol"
	   command sent a router solicitation command *and acted on
	   the returned result* to configure an IPv6 address on the
	   interface *and* configure an IPv6 default route.  None of
	   the commands quoted in this compatibility man page appear
	   to do this(!)

	2. "To quietly send a router solicitation message:" Why on
	   earth would one want to do that?!?  "Quietly" means no
	   debug output is provided, and "send ..." implies that such
	   a message is just sent, but does *not* imply any processing
	   of any returned message.  Or is this just clumsily or
	   imprecisely worded?

	3. The previous example in the man page which adds debug
	   prinout isn't much better in the explanation: it just says
	   "to send a router solicitation message and print
	   information about the response without changing the actual
	   routing table:" says nothing about whether the interface
	   address is changed (probably it isn't).  As such, this also
	   does not provide any replacement functionality to the
	   original "rtsol" command, where one typically want both an
	   IPv6 address configured on the interface *and* setting up
	   an IPv6 default route.

	4. This leaves just the "add the rtsol keyword (on a line by
	   itself?) in /etc/ifconfig.<if>" and using /etc/rc.d/network
	   to fully reconfigure the network as the only option
	   provided via this man page to get the equivalent action as
	   that with "rtsol(d)=yes" in /etc/rc.conf.

	   Also, doing "sh /etc/rc.d/network restart" might disrupt
	   connectivity of ongoing sessions, so is perhaps best done
	   as part of a full reboot / bring-up of the system.

	   No method is given in the man page to do a one-shot
	   configuration of IPv6, something one might want to do for
	   testing before turning it on permanently.


>How-To-Repeat:
	Inspect the rtsold(8) man page in -current or netbsd-10.
>Fix:
	Yes, please.