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

From: Hongren Zheng <[email-masked]>
Date: Sat, 27 Mar 2021 21:36:07 +0800

`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 <[email-masked]>
---
 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)
-- 
2.31.0