* [PATCH iproute2 2/3] ip-link: fix and extend documentation
2015-08-12 20:04 [PATCH iproute2 1/3] ip: fix and extend documentation Pavel Šimerda
@ 2015-08-12 20:04 ` Pavel Šimerda
2015-08-13 6:28 ` vkochan
2015-08-12 20:04 ` [PATCH iproute2 3/3] ip-address: " Pavel Šimerda
1 sibling, 1 reply; 4+ messages in thread
From: Pavel Šimerda @ 2015-08-12 20:04 UTC (permalink / raw)
To: netdev
Cc: Stephen Hemminger, Vadim Kochan, Daniel Borkmann, Phil Sutter,
Pavel Šimerda
From: Pavel Šimerda <psimerda@redhat.com>
* Add `can` to list of supported link types
* Document `addrgenmode`
* Document `link-netnsid`
* Document VLAN link type
* Improve VXLAN link type documentation
- Fix VXLAN srcport/dstport docs
- Document `udpcsum`, `udp6zerocsumtx` and `udp6zerocsumrx`
---
man/man8/ip-link.8.in | 112 ++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 108 insertions(+), 4 deletions(-)
diff --git a/man/man8/ip-link.8.in b/man/man8/ip-link.8.in
index 372e6c6..9ff9a23 100644
--- a/man/man8/ip-link.8.in
+++ b/man/man8/ip-link.8.in
@@ -143,9 +143,13 @@ ip-link \- network device configuration
] |
.br
.B master
-.IR DEVICE
+.IR DEVICE " |"
.br
-.B nomaster
+.B nomaster " |"
+.br
+.B addrgenmode { eui64 | none }
+.br
+.B link-netnsid ID
.BR " }"
@@ -185,6 +189,8 @@ Link types:
.sp
.B bond
- Bonding device
+.B can
+- Controller Area Network interface
.sp
.B dummy
- Dummy network interface
@@ -266,6 +272,66 @@ specifies the number of receive queues for new device.
specifies the desired index of the new virtual device. The link creation fails, if the index is busy.
.TP
+VLAN Type Support
+For a link of type
+.I VLAN
+the following additional arguments are supported:
+
+.BI "ip link add
+.BI link " DEVICE "
+.BI name " NAME "
+.BI type " vlan "
+.R " [ "
+.BI protocol " VLAN_PROTO "
+.R " ] "
+.BI id " VLANID "
+.R " [ "
+.BR reorder_hdr " { " on " | " off " } "
+.R " ] "
+.R " [ "
+.BR gvrp " { " on " | " off " } "
+.R " ] "
+.R " [ "
+.BR mvrp " { " on " | " off " } "
+.R " ] "
+.R " [ "
+.BR loose_binding " { " on " | " off " } "
+.R " ] "
+.R " [ "
+.BI ingress-qos-map " QOS-MAP "
+.R " ] "
+.R " [ "
+.BI egress-qos-map " QOS-MAP "
+.R " ] "
+
+.in +8
+.sp
+.BI protocol " VLAN_PROTO "
+- either 802.1Q or 802.1ad.
+
+.BI id " VLANID "
+- specifies the VLAN Identifer to use. Note that numbers with a leading " 0 " or " 0x " are interpreted as octal or hexadeimal, respectively.
+
+.BR reorder_hdr " { " on " | " off " } "
+- specifies whether ethernet headers are reordered or not.
+
+.BR gvrp " { " on " | " off " } "
+- specifies whether this VLAN should be registered using GARP VLAN Registration Protocol.
+
+.BR mvrp " { " on " | " off " } "
+- specifies whether this VLAN should be registered using Multiple VLAN Registration Protocol.
+
+.BR loose_binding " { " on " | " off " } "
+- specifies whether the VLAN device state is bound to the physical device state.
+
+.BI ingress-qos-map " QOS-MAP "
+- defines a mapping between priority code points on incoming frames. The format is FROM:TO with multiple mappings separated by spaces.
+
+.BI egress-qos-map " QOS-MAP "
+- the same as ingress-qos-map but for outgoing frames.
+.in -8
+
+.TP
VXLAN Type Support
For a link of type
.I VXLAN
@@ -284,7 +350,9 @@ the following additional arguments are supported:
.R " ] [ "
.BI tos " TOS "
.R " ] [ "
-.BI port " MIN MAX "
+.BI dstport " PORT "
+.R " ] [ "
+.BI srcport " MIN MAX "
.R " ] [ "
.I "[no]learning "
.R " ] [ "
@@ -296,6 +364,12 @@ the following additional arguments are supported:
.R " ] [ "
.I "[no]l3miss "
.R " ] [ "
+.I "[no]udpcsum "
+.R " ] [ "
+.I "[no]udp6zerocsumtx "
+.R " ] [ "
+.I "[no]udp6zerocsumrx "
+.R " ] [ "
.BI ageing " SECONDS "
.R " ] [ "
.BI maxaddress " NUMBER "
@@ -340,7 +414,11 @@ parameter.
- specifies the TOS value to use in outgoing packets.
.sp
-.BI port " MIN MAX"
+.BI dstport " PORT"
+- specifies the UDP destination port to communicate to the remote VXLAN tunnel endpoint.
+
+.sp
+.BI srcport " MIN MAX"
- specifies the range of port numbers to use as UDP
source ports to communicate to the remote VXLAN tunnel endpoint.
@@ -366,6 +444,18 @@ are entered into the VXLAN device forwarding database.
- specifies if netlink IP ADDR miss notifications are generated.
.sp
+.I [no]udpcsum
+- specifies if UDP checksum is filled in
+
+.sp
+.I [no]udp6zerocsumtx
+- specifies if UDP checksum is filled in
+
+.sp
+.I [no]udp6zerocsumrx
+- specifies if UDP checksum is received
+
+.sp
.BI ageing " SECONDS"
- specifies the lifetime in seconds of FDB entries learnt by the kernel.
@@ -751,6 +841,12 @@ tool can be used. But it allows to change network namespace only for physical de
give the device a symbolic name for easy reference.
.TP
+.BI group " GROUP"
+specify the group the device belongs to.
+The available groups are listed in file
+.BR "@SYSCONFDIR@/group" .
+
+.TP
.BI vf " NUM"
specify a Virtual Function device to be configured. The associated PF device
must be specified using the
@@ -829,6 +925,14 @@ set master device of the device (enslave device).
.BI nomaster
unset master device of the device (release device).
+.TP
+.BR "addrgenmode eui64 " or " addrgenmode none"
+set IPv6 address generation mode
+
+.TP
+.BR "link-netnsid "
+set peer netnsid for a cross-netns interface
+
.PP
.B Warning:
If multiple parameter changes are requested,
--
2.4.1
^ permalink raw reply related [flat|nested] 4+ messages in thread* [PATCH iproute2 3/3] ip-address: fix and extend documentation
2015-08-12 20:04 [PATCH iproute2 1/3] ip: fix and extend documentation Pavel Šimerda
2015-08-12 20:04 ` [PATCH iproute2 2/3] ip-link: " Pavel Šimerda
@ 2015-08-12 20:04 ` Pavel Šimerda
1 sibling, 0 replies; 4+ messages in thread
From: Pavel Šimerda @ 2015-08-12 20:04 UTC (permalink / raw)
To: netdev
Cc: Stephen Hemminger, Vadim Kochan, Daniel Borkmann, Phil Sutter,
Pavel Šimerda
From: Pavel Šimerda <psimerda@redhat.com>
* Improve manual page synopsis and built-it help
* Use full subcommand names (e.g. 'address' and 'maddress')
* Specify when IPv4, IPv6 or both are affected
* Add lifetimes, home and nodad
* Remove any remaining excess spaces
Commit 43d29f7 substantially improves generated ip-address.8 instead of
ip-address.8.in and commit e419f2d removes the generated one losing the
improvements entirely. This commit recovers the lost changes, adapts
them to the current manual page and adds more man page and help
improvements.
Original commit by: Kenyon Ralph <kenyon@kenyonralph.com>
---
ip/ipaddress.c | 16 +++----
man/man8/ip-address.8.in | 117 +++++++++++++++++++++++++++++++++++++----------
2 files changed, 100 insertions(+), 33 deletions(-)
diff --git a/ip/ipaddress.c b/ip/ipaddress.c
index b7b4e3e..177b65a 100644
--- a/ip/ipaddress.c
+++ b/ip/ipaddress.c
@@ -71,15 +71,15 @@ static void usage(void)
if (do_link) {
iplink_usage();
}
- fprintf(stderr, "Usage: ip addr {add|change|replace} IFADDR dev STRING [ LIFETIME ]\n");
+ fprintf(stderr, "Usage: ip address {add|change|replace} IFADDR dev IFNAME [ LIFETIME ]\n");
fprintf(stderr, " [ CONFFLAG-LIST ]\n");
- fprintf(stderr, " ip addr del IFADDR dev STRING [mngtmpaddr]\n");
- fprintf(stderr, " ip addr {show|save|flush} [ dev STRING ] [ scope SCOPE-ID ]\n");
- fprintf(stderr, " [ to PREFIX ] [ FLAG-LIST ] [ label PATTERN ] [up]\n");
- fprintf(stderr, " ip addr {showdump|restore}\n");
+ fprintf(stderr, " ip address del IFADDR dev IFNAME [mngtmpaddr]\n");
+ fprintf(stderr, " ip address {show|save|flush} [ dev IFNAME ] [ scope SCOPE-ID ]\n");
+ fprintf(stderr, " [ to PREFIX ] [ FLAG-LIST ] [ label LABEL ] [up]\n");
+ fprintf(stderr, " ip address {showdump|restore}\n");
fprintf(stderr, "IFADDR := PREFIX | ADDR peer PREFIX\n");
fprintf(stderr, " [ broadcast ADDR ] [ anycast ADDR ]\n");
- fprintf(stderr, " [ label STRING ] [ scope SCOPE-ID ]\n");
+ fprintf(stderr, " [ label IFNAME ] [ scope SCOPE-ID ]\n");
fprintf(stderr, "SCOPE-ID := [ host | link | global | NUMBER ]\n");
fprintf(stderr, "FLAG-LIST := [ FLAG-LIST ] FLAG\n");
fprintf(stderr, "FLAG := [ permanent | dynamic | secondary | primary |\n");
@@ -1126,7 +1126,7 @@ static int ipadd_dump_check_magic(void)
__u32 magic = 0;
if (isatty(STDIN_FILENO)) {
- fprintf(stderr, "Can't restore addr dump from a terminal\n");
+ fprintf(stderr, "Can't restore address dump from a terminal\n");
return -1;
}
@@ -1878,6 +1878,6 @@ int do_ipaddr(int argc, char **argv)
return ipaddr_restore();
if (matches(*argv, "help") == 0)
usage();
- fprintf(stderr, "Command \"%s\" is unknown, try \"ip addr help\".\n", *argv);
+ fprintf(stderr, "Command \"%s\" is unknown, try \"ip address help\".\n", *argv);
exit(-1);
}
diff --git a/man/man8/ip-address.8.in b/man/man8/ip-address.8.in
index 6e46af8..2ea3e67 100644
--- a/man/man8/ip-address.8.in
+++ b/man/man8/ip-address.8.in
@@ -14,18 +14,26 @@ ip-address \- protocol address management
.sp
.ti -8
-.BR "ip address" " { " add " | " del " } "
-.IB IFADDR " dev " STRING
+.BR "ip address" " { " add " | " change " | " replace " } "
+.IB IFADDR " dev " IFNAME
+.RI "[ " LIFETIME " ] [ " CONFFLAG-LIST " ]"
.ti -8
-.BR "ip address" " { " show " | " flush " } [ " dev
-.IR STRING " ] [ "
+.BR "ip address del"
+.IB IFADDR " dev " IFNAME " [ " mngtmpaddr " ]"
+
+.ti -8
+.BR "ip address" " { " show " | " save " | " flush " } [ " dev
+.IR IFNAME " ] [ "
.B scope
.IR SCOPE-ID " ] [ "
.B to
.IR PREFIX " ] [ " FLAG-LIST " ] [ "
.B label
-.IR PATTERN " ]"
+.IR PATTERN " ] [ " up " ]"
+
+.ti -8
+.BR "ip address" " { " showdump " | " restore " }"
.ti -8
.IR IFADDR " := " PREFIX " | " ADDR
@@ -36,7 +44,7 @@ ip-address \- protocol address management
.B anycast
.IR ADDR " ] [ "
.B label
-.IR STRING " ] [ "
+.IR LABEL " ] [ "
.B scope
.IR SCOPE-ID " ]"
@@ -52,15 +60,33 @@ ip-address \- protocol address management
.IR FLAG " := "
.RB "[ " permanent " | " dynamic " | " secondary " | " primary " | \
[ - ] " tentative " | [ - ] " deprecated " | [ - ] " dadfailed " | "\
-temporary " ]"
+temporary " ] " CONFFLAG-LIST " ]"
+
+.ti -8
+.IR CONFFLAG-LIST " := [ " CONFFLAG-LIST " ] " CONFFLAG
+
+.ti -8
+.IR CONFFLAG " := "
+.RB "[ " home " | " nodad " ]"
+
+.ti -8
+.IR LIFETIME " := [ "
+.BI valid_lft " LFT"
+.RB "| " preferred_lft
+.IR LFT " ]"
+
+.ti -8
+.IR LFT " := [ "
+.BR forever " |"
+.IR SECONDS " ]"
.SH "DESCRIPTION"
The
.B address
-is a protocol (IP or IPv6) address attached
-to a network device. Each device must have at least one address
-to use the corresponding protocol. It is possible to have several
-different addresses attached to one device. These addresses are not
+is a protocol (IPv4 or IPv6) address attached
+to a network device. Each device must have at least one address
+to use the corresponding protocol. It is possible to have several
+different addresses attached to one device. These addresses are not
discriminated, so that the term
.B alias
is not quite appropriate for them and we do not use it in this document.
@@ -73,7 +99,7 @@ and deletes old ones.
.SS ip address add - add new protocol address.
.TP
-.BI dev " NAME"
+.BI dev " IFNAME "
the name of the device to add the address to.
.TP
@@ -107,7 +133,7 @@ instead of the broadcast address. In this case, the broadcast address
is derived by setting/resetting the host bits of the interface prefix.
.TP
-.BI label " NAME"
+.BI label " LABEL"
Each address may be tagged with a label string.
In order to preserve compatibility with Linux-2.0 net aliases,
this string must coincide with the name of the device or must be prefixed
@@ -125,7 +151,7 @@ Predefined scope values are:
- the address is globally valid.
.sp
.B site
-- (IPv6 only) the address is site local, i.e. it is
+- (IPv6 only, deprecated) the address is site local, i.e. it is
valid inside this site.
.sp
.B link
@@ -135,6 +161,30 @@ valid inside this site.
- the address is valid only inside this host.
.in -8
+.TP
+.BI valid_lft " LFT"
+the valid lifetime of this address; see section 5.5.4 of
+RFC 4862. When it expires, the address is removed by the kernel.
+Defaults to
+.BR "forever" .
+
+.TP
+.BI preferred_lft " LFT"
+the preferred lifetime of this address; see section 5.5.4
+of RFC 4862. When it expires, the address is no longer used for new
+outgoing connections. Defaults to
+.BR "forever" .
+
+.TP
+.B home
+(IPv6 only) designates this address the "home address" as defined in
+RFC 6275.
+
+.TP
+.B nodad
+(IPv6 only) do not perform Duplicate Address Detection (RFC 4862) when
+adding this address.
+
.SS ip address delete - delete protocol address
.B Arguments:
coincide with the arguments of
@@ -145,7 +195,7 @@ If no arguments are given, the first address is deleted.
.SS ip address show - look at protocol addresses
.TP
-.BI dev " NAME " (default)
+.BI dev " IFNAME " (default)
name of device.
.TP
@@ -219,36 +269,53 @@ The difference is that it does not run when no arguments are given.
.PP
.B Warning:
-This command (and other
+This command and other
.B flush
-commands described below) is pretty dangerous. If you make a mistake,
-it will not forgive it, but will cruelly purge all the addresses.
+commands are unforgiving. They will cruelly purge all the addresses.
.PP
With the
.B -statistics
option, the command becomes verbose. It prints out the number of deleted
-addresses and the number of rounds made to flush the address list. If
-this option is given twice,
+addresses and the number of rounds made to flush the address list.
+If this option is given twice,
.B ip address flush
also dumps all the deleted addresses in the format described in the
previous subsection.
.SH "EXAMPLES"
.PP
+ip address show
+.RS 4
+Shows IPv4 and IPv6 addresses assigned to all network interfaces. The 'show'
+subcommand can be omitted.
+.RE
+.PP
+ip address show up
+.RS 4
+Same as above except that only addresses assigned to active network interfaces
+are shown.
+.RE
+.PP
ip address show dev eth0
.RS 4
-Shows the addresses assigned to network interface eth0
+Shows IPv4 and IPv6 addresses assigned to network interface eth0.
+.RE
+.PP
+ip address add 2001:0db8:85a3::0370:7334/64 dev eth1
+.RS 4
+Adds an IPv6 address to network interface eth1.
.RE
.PP
-ip addr add 2001:0db8:85a3::0370:7334/64 dev eth1
+ip address delete 2001:0db8:85a3::0370:7334/64 dev eth1
.RS 4
-Adds an IPv6 address to network interface eth1
+Delete the IPv6 address added above.
.RE
.PP
-ip addr flush dev eth4
+ip address flush dev eth4 scope global
.RS 4
-Removes all addresses from device eth4
+Removes all global IPv4 and IPv6 addresses from device eth4. Without 'scope
+global' it would remove all addresses including IPv6 link-local ones.
.RE
.SH SEE ALSO
--
2.4.1
^ permalink raw reply related [flat|nested] 4+ messages in thread