Re: [PATCH iproute2] iptoken: Add doc on the conditions of iptoken

[Stephen Hemminger <stephen@networkplumber.org>]

On Sat, 27 Mar 2021 21:36:07 +0800
Hongren Zheng <i@zenithal.me> wrote:

> `ip token set suffix dev interface' may be unsuccessful
> with only the error 'RTNETLINK answers: Invalid argument'
> prompted. For users this is mysterious and hard to debug.
> Hence a more user-friendly prompt is added.
> 
> This commit adds doc for conditions for setting the token and
> making the token take effect. For the former one, conditions
> in the function 'inet6_set_iftoken' of 'net/ipv6/addrconf.c'
> of the Linux kernel code is documented.
> 
> For the latter one, conditions in the function 'addrconf_prefix_rcv'
> of 'net/ipv6/addrconf.c' of the Linux kernel code is docuemnted.
> 
> Signed-off-by: Hongren Zheng <i@zenithal.me>
> ---
>  ip/iptoken.c        |  4 +++-
>  man/man8/ip-token.8 | 24 ++++++++++++++++++++++++
>  2 files changed, 27 insertions(+), 1 deletion(-)
> 
> diff --git a/ip/iptoken.c b/ip/iptoken.c
> index 9f356890..d56fd68d 100644
> --- a/ip/iptoken.c
> +++ b/ip/iptoken.c
> @@ -177,8 +177,10 @@ static int iptoken_set(int argc, char **argv, bool delete)
>  	addattr_nest_end(&req.n, afs6);
>  	addattr_nest_end(&req.n, afs);
>  
> -	if (rtnl_talk(&rth, &req.n, NULL) < 0)
> +	if (rtnl_talk(&rth, &req.n, NULL) < 0) {
> +		fprintf(stderr, "Conditions not met: 'man ip-token' for more info\n");
>  		return -2;
> +	}
>  
>  	return 0;
>  }
> diff --git a/man/man8/ip-token.8 b/man/man8/ip-token.8
> index 6505b8c5..ac64eb66 100644
> --- a/man/man8/ip-token.8
> +++ b/man/man8/ip-token.8
> @@ -67,6 +67,30 @@ must be left out.
>  list all tokenized interface identifiers for the networking interfaces from
>  the kernel.
>  
> +.SH "NOTES"
> +Several conditions should be met before setting the token for an interface.
> +.RS
> +.IP A
> +\- The interface is not a loopback device.
> +.IP B
> +\- The interface does not have NOARP flag.
> +.IP C
> +\- The interface accepts router advertisement (RA). To be more specific,
> +net.ipv6.conf.interface.accept_ra=1,
> +and when net.ipv6.conf.interface.forwarding=1,
> +net.ipv6.conf.interface.accept_ra=2.
> +.RE
> +
> +For the token to take effect, several conditions should be met.
> +.RS
> +.IP A
> +\- The interface has autoconf flag turned on. To be more specific, net.ipv6.conf.interface.autoconf=1
> +.IP B
> +\- The router advertisement (RA) has autonomous address-configuration flag turned on.
> +.IP C
> +\- The length of the prefix in the router advertisement (RA) is 64.
> +.RE
> +
>  .SH SEE ALSO
>  .br
>  .BR ip (8)

It would be better if kernel provided the error messages through external ack
of the netlink message, rather than providing potentially out of date
recommendations on the man page.