[iproute PATCH 0/6] iplink: Improve documentation

[iproute PATCH 0/6] iplink: Improve documentation

[Phil Sutter]

This series improves documentation around the feature of 'ip link set'
to configure device type specific parameters. While doing so, I reviewed
used fonts in ip-link.8 and fixed a few bugs/inconsistencies.

Phil Sutter (6):
  iplink: List valid 'type' argument in ip link help text
  iplink: bond_slave: Add missing help functions
  ip-link.8: Extend type list in synopsis
  ip-link.8: Place 'ip link set' warning more prominently
  ip-link.8: Add slave type option descriptions
  ip-link.8: Fix font choices

 ip/iplink.c            |   4 +-
 ip/iplink_bond_slave.c |  24 ++++
 man/man8/ip-link.8.in  | 314 +++++++++++++++++++++++++++++++++++--------------
 3 files changed, 254 insertions(+), 88 deletions(-)

-- 
2.8.2

[iproute PATCH 1/6] iplink: List valid 'type' argument in ip link help text

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 ip/iplink.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/ip/iplink.c b/ip/iplink.c
index f2a2e13cf0c5b..0e3cee6af8b6f 100644
--- a/ip/iplink.c
+++ b/ip/iplink.c
@@ -55,7 +55,9 @@ void iplink_usage(void)
 		fprintf(stderr, "                   type TYPE [ ARGS ]\n");
 		fprintf(stderr, "       ip link delete { DEVICE | dev DEVICE | group DEVGROUP } type TYPE [ ARGS ]\n");
 		fprintf(stderr, "\n");
-		fprintf(stderr, "       ip link set { DEVICE | dev DEVICE | group DEVGROUP } [ { up | down } ]\n");
+		fprintf(stderr, "       ip link set { DEVICE | dev DEVICE | group DEVGROUP }\n");
+		fprintf(stderr, "	                  [ { up | down } ]\n");
+		fprintf(stderr, "	                  [ type TYPE ARGS ]\n");
 	} else
 		fprintf(stderr, "Usage: ip link set DEVICE [ { up | down } ]\n");
 
-- 
2.8.2

[iproute PATCH 2/6] iplink: bond_slave: Add missing help functions

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 ip/iplink_bond_slave.c | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/ip/iplink_bond_slave.c b/ip/iplink_bond_slave.c
index d67793237edfc..9c60dea8a2757 100644
--- a/ip/iplink_bond_slave.c
+++ b/ip/iplink_bond_slave.c
@@ -17,6 +17,16 @@
 #include "utils.h"
 #include "ip_common.h"
 
+static void print_explain(FILE *f)
+{
+	fprintf(f, "Usage: ... bond_slave [ queue_id ID ]\n");
+}
+
+static void explain(void)
+{
+	print_explain(stderr);
+}
+
 static const char *slave_states[] = {
 	[BOND_STATE_ACTIVE] = "ACTIVE",
 	[BOND_STATE_BACKUP] = "BACKUP",
@@ -99,6 +109,13 @@ static int bond_slave_parse_opt(struct link_util *lu, int argc, char **argv,
 			if (get_u16(&queue_id, *argv, 0))
 				invarg("queue_id is invalid", *argv);
 			addattr16(n, 1024, IFLA_BOND_SLAVE_QUEUE_ID, queue_id);
+		} else {
+			if (matches(*argv, "help") != 0)
+				fprintf(stderr,
+					"bond_slave: unknown option \"%s\"?\n",
+					*argv);
+			explain();
+			return -1;
 		}
 		argc--, argv++;
 	}
@@ -106,10 +123,17 @@ static int bond_slave_parse_opt(struct link_util *lu, int argc, char **argv,
 	return 0;
 }
 
+static void bond_slave_print_help(struct link_util *lu, int argc, char **argv,
+				  FILE *f)
+{
+	print_explain(f);
+}
+
 struct link_util bond_slave_link_util = {
 	.id		= "bond",
 	.maxattr	= IFLA_BOND_SLAVE_MAX,
 	.print_opt	= bond_slave_print_opt,
 	.parse_opt	= bond_slave_parse_opt,
+	.print_help	= bond_slave_print_help,
 	.slave		= true,
 };
-- 
2.8.2

[iproute PATCH 3/6] ip-link.8: Extend type list in synopsis

[Phil Sutter]

'ip link set' supports passing a type to set type-specific parameters.
Add this missing piece of information to the synopsis section.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/ip-link.8.in | 71 +++++++++++++++++++++++++++++----------------------
 1 file changed, 40 insertions(+), 31 deletions(-)

diff --git a/man/man8/ip-link.8.in b/man/man8/ip-link.8.in
index ad18f7555d0a5..4fc5f3c6257e5 100644
--- a/man/man8/ip-link.8.in
+++ b/man/man8/ip-link.8.in
@@ -40,35 +40,6 @@ ip-link \- network device configuration
 .RI "[ " ARGS " ]"
 
 .ti -8
-.IR TYPE " := [ "
-.BR bridge " | "
-.BR bond " | "
-.BR can " | "
-.BR dummy " | "
-.BR hsr " | "
-.BR ifb " | "
-.BR ipoib " |"
-.BR macvlan  " | "
-.BR macvtap  " | "
-.BR vcan " | "
-.BR veth " | "
-.BR vlan " | "
-.BR vxlan " |"
-.BR ip6tnl " |"
-.BR ipip " |"
-.BR sit " |"
-.BR gre " |"
-.BR gretap " |"
-.BR ip6gre " |"
-.BR ip6gretap " |"
-.BR vti " |"
-.BR nlmon " |"
-.BR ipvlan " |"
-.BR lowpan " |"
-.BR geneve " |"
-.BR vrf " ]"
-
-.ti -8
 .BR "ip link delete " {
 .IR DEVICE " | "
 .BI "group " GROUP
@@ -80,7 +51,12 @@ ip-link \- network device configuration
 .BR "ip link set " {
 .IR DEVICE " | "
 .BI "group " GROUP
-.RB "} [ { " up " | " down " } ]"
+}
+.br
+.RB "[ { " up " | " down " } ]"
+.br
+.RB "[ " type
+.IR "ETYPE TYPE_ARGS" " ]"
 .br
 .RB "[ " arp " { " on " | " off " } ]"
 .br
@@ -169,7 +145,7 @@ ip-link \- network device configuration
 .B master
 .IR DEVICE " ] ["
 .B type
-.IR TYPE " ]"
+.IR ETYPE " ]"
 .B vrf
 .IR NAME " ]"
 
@@ -177,6 +153,39 @@ ip-link \- network device configuration
 .B ip link help
 .RI "[ " TYPE " ]"
 
+.ti -8
+.IR TYPE " := [ "
+.BR bridge " | "
+.BR bond " | "
+.BR can " | "
+.BR dummy " | "
+.BR hsr " | "
+.BR ifb " | "
+.BR ipoib " |"
+.BR macvlan  " | "
+.BR macvtap  " | "
+.BR vcan " | "
+.BR veth " | "
+.BR vlan " | "
+.BR vxlan " |"
+.BR ip6tnl " |"
+.BR ipip " |"
+.BR sit " |"
+.BR gre " |"
+.BR gretap " |"
+.BR ip6gre " |"
+.BR ip6gretap " |"
+.BR vti " |"
+.BR nlmon " |"
+.BR ipvlan " |"
+.BR lowpan " |"
+.BR geneve " |"
+.BR vrf " ]"
+
+.ti -8
+.IR ETYPE " := [ " TYPE " |"
+.BR bridge_slave " | " bond_slave " ]"
+
 .SH "DESCRIPTION"
 .SS ip link add - add virtual link
 
-- 
2.8.2

[iproute PATCH 4/6] ip-link.8: Place 'ip link set' warning more prominently

[Phil Sutter]

This moves the warning to the beginning of the section about 'ip link
set' which makes it still stand out after adding more text to it's end.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/ip-link.8.in | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/man/man8/ip-link.8.in b/man/man8/ip-link.8.in
index 4fc5f3c6257e5..2678d37df7478 100644
--- a/man/man8/ip-link.8.in
+++ b/man/man8/ip-link.8.in
@@ -1015,6 +1015,18 @@ specifies the type of the device.
 
 .SS ip link set - change device attributes
 
+.PP
+.B Warning:
+If multiple parameter changes are requested,
+.B ip
+aborts immediately after any of the changes have failed.
+This is the only case when
+.B ip
+can move the system to an unpredictable state. The solution
+is to avoid changing several parameters with one
+.B ip link set
+call.
+
 .TP
 .BI dev " DEVICE "
 .I DEVICE
@@ -1235,18 +1247,6 @@ set the IPv6 address generation mode
 .BR "link-netnsid "
 set peer netnsid for a cross-netns interface
 
-.PP
-.B Warning:
-If multiple parameter changes are requested,
-.B ip
-aborts immediately after any of the changes have failed.
-This is the only case when
-.B ip
-can move the system to an unpredictable state. The solution
-is to avoid changing several parameters with one
-.B ip link set
-call.
-
 .SS  ip link show - display device attributes
 
 .TP
-- 
2.8.2

[iproute PATCH 5/6] ip-link.8: Add slave type option descriptions

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/ip-link.8.in | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/man/man8/ip-link.8.in b/man/man8/ip-link.8.in
index 2678d37df7478..ada20fe210793 100644
--- a/man/man8/ip-link.8.in
+++ b/man/man8/ip-link.8.in
@@ -1247,6 +1247,135 @@ set the IPv6 address generation mode
 .BR "link-netnsid "
 set peer netnsid for a cross-netns interface
 
+.TP
+.BI type " ETYPE TYPE_ARGS"
+Change type-specific settings. For a list of supported types and arguments refer
+to the description of
+.B "ip link add"
+above. In addition to that, it is possible to manipulate settings to slave
+devices:
+
+.TP
+Bridge Slave Support
+For a link with master
+.B bridge
+the following additional arguments are supported:
+
+.B "ip link set type bridge_slave"
+[
+.BI state " STATE"
+] [
+.BI priority " PRIO"
+] [
+.BI cost " COST"
+] [
+.BR guard " { " on " | " off " }"
+] [
+.BR hairpin " { " on " | " off " }"
+] [
+.BR fastleave " { " on " | " off " }"
+] [
+.BR root_block " { " on " | " off " }"
+] [
+.BR learning " { " on " | " off " }"
+] [
+.BR flood " { " on " | " off " }"
+] [
+.BR proxy_arp " { " on " | " off " }"
+] [
+.BR proxy_arp_wifi " { " on " | " off " }"
+] [
+.BI mcast_router " MULTICAST_ROUTER"
+] [
+.BR mcast_fast_leave " { " on " | " off "} ]"
+
+.in +8
+.sp
+.BI state " STATE"
+- Set port state.
+.I STATE
+is a number representing the following states:
+.BR 0 " (disabled),"
+.BR 1 " (listening),"
+.BR 2 " (learning),"
+.BR 3 " (forwarding),"
+.BR 4 " (blocking)."
+
+.BI priority " PRIO"
+- set port priority (a 16bit unsigned value).
+
+.BI cost " COST"
+- set port cost (a 32bit unsigned value).
+
+.BR guard " { " on " | " off " }"
+- block incoming BPDU packets on this port.
+
+.BR hairpin " { " on " | " off " }"
+- enable hairpin mode on this port. This will allow incoming packets on this
+port to be reflected back.
+
+.BR fastleave " { " on " | " off " }"
+- enable multicast fast leave on this port.
+
+.BR root_block " { " on " | " off " }"
+- block this port from becoming the bridge's root port.
+
+.BR learning " { " on " | " off " }"
+- allow MAC address learning on this port.
+
+.BR flood " { " on " | " off " }"
+- open the flood gates on this port, i.e. forward all unicast frames to this
+port also. Requires
+.BR proxy_arp " and " proxy_arp_wifi
+to be turned off.
+
+.BR proxy_arp " { " on " | " off " }"
+- enable proxy ARP on this port.
+
+.BR proxy_arp_wifi " { " on " | " off " }"
+- enable proxy ARP on this port which meets extended requirements by IEEE
+802.11 and Hotspot 2.0 specifications.
+
+.BI mcast_router " MULTICAST_ROUTER"
+- configure this port for having multicast routers attached. A port with a
+multicast router will receive all multicast traffic.
+.I MULTICAST_ROUTER
+may be either
+.B 0
+to disable multicast routers on this port,
+.B 1
+to let the system detect the presence of of routers (this is the default),
+.B 2
+to permanently enable multicast traffic forwarding on this port or
+.B 3
+to enable multicast routers temporarily on this port, not depending on incoming
+queries.
+
+.BR mcast_fast_leave " { " on " | " off " }"
+- this is a synonym to the
+.B fastleave
+option above.
+
+.in -8
+
+.TP
+Bonding Slave Support
+For a link with master
+.B bond
+the following additional arguments are supported:
+
+.B "ip link set type bond_slave"
+[
+.BI queue_id " ID"
+]
+
+.in +8
+.sp
+.BI queue_id " ID"
+- set the slave's queue ID (a 16bit unsigned value).
+
+.in -8
+
 .SS  ip link show - display device attributes
 
 .TP
-- 
2.8.2

[iproute PATCH 6/6] ip-link.8: Fix font choices

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/ip-link.8.in | 92 ++++++++++++++++++++++++++-------------------------
 1 file changed, 47 insertions(+), 45 deletions(-)

diff --git a/man/man8/ip-link.8.in b/man/man8/ip-link.8.in
index ada20fe210793..1644af0ef9f9f 100644
--- a/man/man8/ip-link.8.in
+++ b/man/man8/ip-link.8.in
@@ -304,7 +304,7 @@ the following additional arguments are supported:
 .BI "ip link add
 .BI link " DEVICE "
 .BI name " NAME "
-.BI type " vlan "
+.B "type vlan"
 [
 .BI protocol " VLAN_PROTO "
 ]
@@ -406,7 +406,7 @@ For a link of type
 the following additional arguments are supported:
 
 .BI "ip link add " DEVICE
-.BI type " vxlan " id " ID"
+.BI type " vxlan " id " VNI"
 [
 .BI dev " PHYS_DEV "
 .RB " ] [ { " group " | " remote " } "
@@ -425,27 +425,27 @@ the following additional arguments are supported:
 ] [
 .BI srcport " MIN MAX "
 ] [
-.I "[no]learning "
+.RB [ no ] learning
 ] [
-.I "[no]proxy "
+.RB [ no ] proxy
 ] [
-.I "[no]rsc "
+.RB [ no ] rsc
 ] [
-.I "[no]l2miss "
+.RB [ no ] l2miss
 ] [
-.I "[no]l3miss "
+.RB [ no ] l3miss
 ] [
-.I "[no]udpcsum "
+.RB [ no ] udpcsum
 ] [
-.I "[no]udp6zerocsumtx "
+.RB [ no ] udp6zerocsumtx
 ] [
-.I "[no]udp6zerocsumrx "
+.RB [ no ] udp6zerocsumrx
 ] [
 .BI ageing " SECONDS "
 ] [
 .BI maxaddress " NUMBER "
 ] [
-.RI "[no]external "
+.RB [ no ] external
 ] [
 .B gbp
 ] [
@@ -502,36 +502,36 @@ parameter.
 source ports to communicate to the remote VXLAN tunnel endpoint.
 
 .sp
-.I [no]learning
+.RB [ no ] learning
 - specifies if unknown source link layer addresses and IP addresses
 are entered into the VXLAN device forwarding database.
 
 .sp
-.I [no]rsc
+.RB [ no ] rsc
 - specifies if route short circuit is turned on.
 
 .sp
-.I [no]proxy
+.RB [ no ] proxy
 - specifies ARP proxy is turned on.
 
 .sp
-.I [no]l2miss
+.RB [ no ] l2miss
 - specifies if netlink LLADDR miss notifications are generated.
 
 .sp
-.I [no]l3miss
+.RB [ no ] l3miss
 - specifies if netlink IP ADDR miss notifications are generated.
 
 .sp
-.I [no]udpcsum
+.RB [ no ] udpcsum
 - specifies if UDP checksum is calculated for transmitted packets over IPv4.
 
 .sp
-.I [no]udp6zerocsumtx
+.RB [ no ] udp6zerocsumtx
 - skip UDP checksum calculation for transmitted packets over IPv6.
 
 .sp
-.I [no]udp6zerocsumrx
+.RB [ no ] udp6zerocsumrx
 - allow incoming UDP packets over IPv6 with zero checksum field.
 
 .sp
@@ -543,7 +543,7 @@ are entered into the VXLAN device forwarding database.
 - specifies the maximum number of FDB entries.
 
 .sp
-.I [no]external
+.RB [ no ] external
 - specifies whether an external control plane
 .RB "(e.g. " "ip route encap" )
 or the internal FDB should be used.
@@ -607,18 +607,18 @@ For a link of types
 the following additional arguments are supported:
 
 .BI "ip link add " DEVICE
-.BR type " { gre | ipip | sit } "
+.BR type " { " gre " | " ipip " | " sit " }"
 .BI " remote " ADDR " local " ADDR
 [
-.BR encap " { fou | gue | none } "
+.BR encap " { " fou " | " gue " | " none " }"
 ] [
-.BI "encap-sport { " PORT " | auto } "
+.BR encap-sport " { " \fIPORT " | " auto " }"
 ] [
 .BI "encap-dport " PORT
 ] [
-.I " [no]encap-csum "
+.RB [ no ] encap-csum
 ] [
-.I " [no]encap-remcsum "
+.RB [ no ] encap-remcsum
 ]
 
 .in +8
@@ -632,12 +632,12 @@ the following additional arguments are supported:
 It must be an address on another interface on this host.
 
 .sp
-.BR encap " { fou | gue | none } "
+.BR encap " { " fou " | " gue " | " none " }"
 - specifies type of secondary UDP encapsulation. "fou" indicates
 Foo-Over-UDP, "gue" indicates Generic UDP Encapsulation.
 
 .sp
-.BI "encap-sport { " PORT " | auto } "
+.BR encap-sport " { " \fIPORT " | " auto " }"
 - specifies the source port in UDP encapsulation.
 .IR PORT
 indicates the port by number, "auto"
@@ -646,12 +646,12 @@ indicates that the port number should be chosen automatically
 encapsulated packet).
 
 .sp
-.I [no]encap-csum
+.RB [ no ] encap-csum
 - specifies if UDP checksums are enabled in the secondary
 encapsulation.
 
 .sp
-.I [no]encap-remcsum
+.RB [ no ] encap-remcsum
 - specifies if Remote Checksum Offload is enabled. This is only
 applicable for Generic UDP Encapsulation.
 
@@ -664,13 +664,15 @@ For a link of type
 the following additional arguments are supported:
 
 .BI "ip link add " DEVICE
-.BI type " { ip6gre | ip6gretap }  " remote " ADDR " local " ADDR
+.BR type " { " ip6gre " | " ip6gretap " }"
+.BI remote " ADDR " local " ADDR"
 [
-.I "[i|o]seq]"
+.RB [ i | o ] seq
 ] [
-.I "[i|o]key" KEY
+.RB [ i | o ] key
+.I KEY
 ] [
-.I " [i|o]csum "
+.RB [ i | o ] csum
 ] [
 .BI hoplimit " TTL "
 ] [
@@ -696,7 +698,7 @@ the following additional arguments are supported:
 It must be an address on another interface on this host.
 
 .sp
-.BI  [i|o]seq
+.RB  [ i | o ] seq
 - serialize packets.
 The
 .B oseq
@@ -706,7 +708,7 @@ The
 flag requires that all input packets are serialized.
 
 .sp
-.BI  [i|o]key " KEY"
+.RB  [ i | o ] key " \fIKEY"
 - use keyed GRE with key
 .IR KEY ". "KEY
 is either a number or an IPv4 address-like dotted quad.
@@ -718,7 +720,7 @@ The
 parameters specify different keys for input and output.
 
 .sp
-.BI  [i|o]csum
+.RB  [ i | o ] csum
 - generate/require checksums for tunneled packets.
 The
 .B ocsum
@@ -770,7 +772,7 @@ For a link of type
 the following additional arguments are supported:
 
 .BI "ip link add " DEVICE " name " NAME
-.BI type " ipoib [ " pkey " PKEY ] [" mode " MODE " ]
+.BR "type ipoib " [ " pkey \fIPKEY" " ] [ " mode " \fIMODE \fR]"
 
 .in +8
 .sp
@@ -787,7 +789,7 @@ For a link of type
 the following additional arguments are supported:
 
 .BI "ip link add " DEVICE
-.BI type " geneve " id " ID " remote " IPADDR"
+.BI type " geneve " id " VNI " remote " IPADDR"
 [
 .BI ttl " TTL "
 ] [
@@ -830,7 +832,7 @@ the following additional arguments are supported:
 .BI "ip link add link " DEVICE " name " NAME
 .BR type " { " macvlan " | " macvtap " } "
 .BR mode " { " private " | " vepa " | " bridge " | " passthru
-.BR " [ " nopromisc " ] } "
+.RB " [ " nopromisc " ] } "
 
 .in +8
 .sp
@@ -875,11 +877,11 @@ For a link of type
 .I HSR
 the following additional arguments are supported:
 
-.BI "ip link add link " DEVICE " name " NAME
-.BI type " hsr "
+.BI "ip link add link " DEVICE " name " NAME " type hsr"
 .BI slave1 " SLAVE1-IF " slave2 " SLAVE2-IF "
-.BR " [ supervision " ADDR-BYTE "  ] "
-.BR " [ version  { " 0 " | " 1 " } ] "
+.RB [ " supervision"
+.IR ADDR-BYTE " ] ["
+.BR version " { " 0 " | " 1 " } ]"
 
 .in +8
 .sp
@@ -892,11 +894,11 @@ the following additional arguments are supported:
 .BI slave2 " SLAVE2-IF "
 - Specifies the physical device used for the second of the two ring ports.
 
-.BR "supervision ADDR-BYTE "
+.BI supervision " ADDR-BYTE"
 - The last byte of the multicast address used for HSR supervision frames.
 Default option is "0", possible values 0-255.
 
-.BR "version { 0 | 1 }"
+.BR version " { " 0 " | " 1 " }"
 - Selects the protocol version of the interface. Default option is "0", which
 corresponds to the 2010 version of the HSR standard. Option "1" activates the
 2012 version.
-- 
2.8.2

Re: [iproute PATCH 0/6] iplink: Improve documentation

[Stephen Hemminger]

On Sat,  9 Jul 2016 11:22:44 +0200
Phil Sutter <phil@nwl.cc> wrote:

> This series improves documentation around the feature of 'ip link set'
> to configure device type specific parameters. While doing so, I reviewed
> used fonts in ip-link.8 and fixed a few bugs/inconsistencies.
> 
> Phil Sutter (6):
>   iplink: List valid 'type' argument in ip link help text
>   iplink: bond_slave: Add missing help functions
>   ip-link.8: Extend type list in synopsis
>   ip-link.8: Place 'ip link set' warning more prominently
>   ip-link.8: Add slave type option descriptions
>   ip-link.8: Fix font choices
> 
>  ip/iplink.c            |   4 +-
>  ip/iplink_bond_slave.c |  24 ++++
>  man/man8/ip-link.8.in  | 314 +++++++++++++++++++++++++++++++++++--------------
>  3 files changed, 254 insertions(+), 88 deletions(-)
> 

Applied thanks