| Message ID | YF80x4bBaXpS4s/W@Sun (mailing list archive) |
|---|---|
| State | Changes Requested |
| Delegated to: | Stephen Hemminger |
| Headers | show |
| Series | [iproute2] iptoken: Add doc on the conditions of iptoken | expand |
| Context | Check | Description |
|---|---|---|
| netdev/tree_selection | success | Not a local patch |
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.
On Wed, Mar 31, 2021 at 03:26:02PM -0700, Stephen Hemminger wrote: > It would be better if kernel provided the error messages through external ack > of the netlink message, Agreed. > rather than providing potentially out of date > recommendations on the man page. I still think conditions for ip-token to be accepted and take effect should be documented on the man page. Errors in kernel extack only give hints to users in case they forget to configure some flags. For new users, a complete condition reference should be documented for them to evaluate the use case of ip-token. Also the autoconf flag would not prompt errors when the user forgets to turn it on, this is unexpected when the user does intend to use ip-token. Even /proc/sys interface may be out of date, these conditions may remain unchanged or only be altered slightly, hence documenting them does not hurt.
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)
`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(-)