.TH IP\-LINK 8 "13 Dec 2012" "iproute2" "Linux"

.SH "NAME"

ip-link \- network device configuration

.SH "SYNOPSIS"

.sp

.ad l

.in +8

.ti -8

.B ip link

.RI  " { " COMMAND " | "

.BR help " }"

.sp

.ti -8

.BI "ip link add"

.RB "[ " link

.IR DEVICE " ]"

.RB "[ " name " ]"

.I NAME

.br

.RB "[ " txqueuelen

.IR PACKETS " ]"

.br

.RB "[ " address

.IR LLADDR " ]"

.RB "[ " broadcast

.IR LLADDR " ]"

.br

.RB "[ " mtu

.IR MTU " ]"

.RB "[ " index

.IR IDX " ]"

.br

.RB "[ " numtxqueues

.IR QUEUE_COUNT " ]"

.RB "[ " numrxqueues

.IR QUEUE_COUNT " ]"

.br

.BR "[ " gso_max_size

.IR BYTES " ]"

.RB "[ " gso_max_segs

.IR SEGMENTS " ]"

.br

.BI type " TYPE"

.RI "[ " ARGS " ]"

.ti -8

.BR "ip link delete " {

.IR DEVICE " | "

.BI "group " GROUP

}

.BI type " TYPE"

.RI "[ " ARGS " ]"

.ti -8

.BR "ip link set " {

.IR DEVICE " | "

.BI "group " GROUP

}

.br

.RB "[ { " up " | " down " } ]"

.br

.RB "[ " type

.IR "ETYPE TYPE_ARGS" " ]"

.br

.RB "[ " arp " { " on " | " off " } ]"

.br

.RB "[ " dynamic " { " on " | " off " } ]"

.br

.RB "[ " multicast " { " on " | " off " } ]"

.br

.RB "[ " allmulticast " { " on " | " off " } ]"

.br

.RB "[ " promisc " { " on " | " off " } ]"

.br

.RB "[ " protodown " { " on " | " off " } ]"

.br

.RB "[ " trailers " { " on " | " off " } ]"

.br

.RB "[ " txqueuelen

.IR PACKETS " ]"

.br

.RB "[ " name

.IR NEWNAME " ]"

.br

.RB "[ " address

.IR LLADDR " ]"

.br

.RB "[ " broadcast

.IR LLADDR " ]"

.br

.RB "[ " mtu

.IR MTU " ]"

.br

.RB "[ " netns " {"

.IR PID " | " NETNSNAME " } ]"

.br

.RB "[ " link-netnsid

.IR ID " ]"

.br

.RB "[ " alias

.IR NAME  " ]"

.br

.RB "[ " vf

.IR NUM " ["

.B  mac

.IR LLADDR " ]"

.br

.in +9

.RI "[ " VFVLAN-LIST " ]"

.br

.RB "[ " rate

.IR TXRATE " ]"

.br

.RB "[ " max_tx_rate

.IR TXRATE " ]"

.br

.RB "[ " min_tx_rate

.IR TXRATE " ]"

.br

.RB "[ " spoofchk " { " on " | " off " } ]"

.br

.RB "[ " query_rss " { " on " | " off " } ]"

.br

.RB "[ " state " { " auto " | " enable " | " disable " } ]"

.br

.RB "[ " trust " { " on " | " off " } ]"

.br

.RB "[ " node_guid " eui64 ]"

.br

.RB "[ " port_guid " eui64 ] ]"

.br

.in -9

.RB "[ { " xdp " | " xdpgeneric  " | " xdpdrv " | " xdpoffload " } { " off " | "

.br

.in +8

.BR object

.IR FILE

.RB "[ " section

.IR NAME " ]"

.RB "[ " verbose " ] |"

.br

.BR pinned

.IR FILE " } ]"

.br

.in -8

.RB "[ " master

.IR DEVICE " ]"

.br

.RB "[ " nomaster " ]"

.br

.RB "[ " vrf

.IR NAME " ]"

.br

.RB "[ " addrgenmode " { " eui64 " | " none " | " stable_secret " | " random " } ]"

.br

.RB "[ " macaddr

.RI "[ " MACADDR " ]"

.br

.in +10

.RB "[ { " flush " | " add " | " del " } "

.IR MACADDR " ]"

.br

.RB "[ " set

.IR MACADDR " ] ]"

.br

.ti -8

.B ip link show

.RI "[ " DEVICE " | "

.B group

.IR GROUP " ] ["

.BR up " ] ["

.B master

.IR DEVICE " ] ["

.B type

.IR ETYPE " ] ["

.B vrf

.IR NAME " ]"

.ti -8

.B ip link xstats

.BI type " TYPE"

.RI "[ " ARGS " ]"

.ti -8

.B ip link afstats

.RB "[ " dev

.IR DEVICE " ]"

.ti -8

.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 vxcan " | "

.BR veth " | "

.BR vlan " | "

.BR vxlan " |"

.BR ip6tnl " |"

.BR ipip " |"

.BR sit " |"

.BR gre " |"

.BR gretap " |"

.BR erspan " |"

.BR ip6gre " |"

.BR ip6gretap " |"

.BR ip6erspan " |"

.BR vti " |"

.BR nlmon " |"

.BR ipvlan " |"

.BR ipvtap " |"

.BR lowpan " |"

.BR geneve " |"

.BR bareudp " |"

.BR vrf " |"

.BR macsec " |"

.BR netdevsim " |"

.BR rmnet " |"

.BR xfrm " ]"

.ti -8

.IR ETYPE " := [ " TYPE " |"

.BR bridge_slave " | " bond_slave " ]"

.ti -8

.IR VFVLAN-LIST " := [ "  VFVLAN-LIST " ] " VFVLAN

.ti -8

.IR VFVLAN " := "

.RB "[ " vlan

.IR VLANID " [ "

.B qos

.IR VLAN-QOS " ] ["

.B proto

.IR VLAN-PROTO " ] ]"

.in -8

.ti -8

.BI "ip link property add"

.RB "[ " altname

.IR NAME " .. ]"

.ti -8

.BI "ip link property del"

.RB "[ " altname

.IR NAME " .. ]"

.SH "DESCRIPTION"

.SS ip link add - add virtual link

.TP

.BI link " DEVICE "

specifies the physical device to act operate on.

.I NAME

specifies the name of the new virtual device.

.I TYPE

specifies the type of the new device.

.sp

Link types:

.in +8

.B bridge

- Ethernet Bridge device

.sp

.B bond

- Bonding device

.sp

.B dummy

- Dummy network interface

.sp

.B hsr

- High-availability Seamless Redundancy device

.sp

.B ifb

- Intermediate Functional Block device

.sp

.B ipoib

- IP over Infiniband device

.sp

.B macvlan

- Virtual interface base on link layer address (MAC)

.sp

.B macvtap

- Virtual interface based on link layer address (MAC) and TAP.

.sp

.B vcan

- Virtual Controller Area Network interface

.sp

.B vxcan

- Virtual Controller Area Network tunnel interface

.sp

.B veth

- Virtual ethernet interface

.sp

.BR vlan

- 802.1q tagged virtual LAN interface

.sp

.BR vxlan

- Virtual eXtended LAN

.sp

.BR ip6tnl

- Virtual tunnel interface IPv4|IPv6 over IPv6

.sp

.BR ipip

- Virtual tunnel interface IPv4 over IPv4

.sp

.BR sit

- Virtual tunnel interface IPv6 over IPv4

.sp

.BR gre

- Virtual tunnel interface GRE over IPv4

.sp

.BR gretap

- Virtual L2 tunnel interface GRE over IPv4

.sp

.BR erspan

- Encapsulated Remote SPAN over GRE and IPv4

.sp

.BR ip6gre

- Virtual tunnel interface GRE over IPv6

.sp

.BR ip6gretap

- Virtual L2 tunnel interface GRE over IPv6

.sp

.BR ip6erspan

- Encapsulated Remote SPAN over GRE and IPv6

.sp

.BR vti

- Virtual tunnel interface

.sp

.BR nlmon

- Netlink monitoring device

.sp

.BR ipvlan

- Interface for L3 (IPv6/IPv4) based VLANs

.sp

.BR ipvtap

- Interface for L3 (IPv6/IPv4) based VLANs and TAP

.sp

.BR lowpan

- Interface for 6LoWPAN (IPv6) over IEEE 802.15.4 / Bluetooth

.sp

.BR geneve

- GEneric NEtwork Virtualization Encapsulation

.sp

.BR bareudp

- Bare UDP L3 encapsulation support

.sp

.BR macsec

- Interface for IEEE 802.1AE MAC Security (MACsec)

.sp

.BR vrf

- Interface for L3 VRF domains

.sp

.BR netdevsim

- Interface for netdev API tests

.sp

.BR rmnet

- Qualcomm rmnet device

.sp

.BR xfrm

- Virtual xfrm interface

.in -8

.TP

.BI numtxqueues " QUEUE_COUNT "

specifies the number of transmit queues for new device.

.TP

.BI numrxqueues " QUEUE_COUNT "

specifies the number of receive queues for new device.

.TP

.BI gso_max_size " BYTES "

specifies the recommended maximum size of a Generic Segment Offload

packet the new device should accept.

.TP

.BI gso_max_segs " SEGMENTS "

specifies the recommended maximum number of a Generic Segment Offload

segments the new device should accept.

.TP

.BI index " IDX "

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 "

.B "type vlan"

[

.BI protocol " VLAN_PROTO "

]

.BI id " VLANID "

[

.BR reorder_hdr " { " on " | " off " } "

]

[

.BR gvrp " { " on " | " off " } "

]

[

.BR mvrp " { " on " | " off " } "

]

[

.BR loose_binding " { " on " | " off " } "

]

[

.BR bridge_binding " { " on " | " off " } "

]

[

.BI ingress-qos-map " QOS-MAP "

]

[

.BI egress-qos-map " QOS-MAP "

]

.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 (default is

.BR on ")."

.in +4

If

.BR reorder_hdr " is " on

then VLAN header will be not inserted immediately but only before

passing to the physical device (if this device does not support VLAN

offloading), the similar on the RX direction - by default the packet

will be untagged before being received by VLAN device. Reordering

allows to accelerate tagging on egress and to hide VLAN header on

ingress so the packet looks like regular Ethernet packet, at the same

time it might be confusing for packet capture as the VLAN header does

not exist within the packet.

VLAN offloading can be checked by

.BR ethtool "(8):"

.in +4

.sp

.B ethtool -k

<phy_dev> |

.RB grep " tx-vlan-offload"

.sp

.in -4

where <phy_dev> is the physical device to which VLAN device is bound.

.in -4

.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.

.BR bridge_binding " { " on " | " off " } "

- specifies whether the VLAN device link state tracks the state of bridge ports

that are members of the VLAN.

.BI ingress-qos-map " QOS-MAP "

- defines a mapping of VLAN header prio field to the Linux internal packet

priority on incoming frames. The format is FROM:TO with multiple mappings

separated by spaces.

.BI egress-qos-map " QOS-MAP "

- defines a mapping of Linux internal packet priority to VLAN header prio field

but for outgoing frames. The format is the same as for ingress-qos-map.

.in +4

Linux packet priority can be set by

.BR iptables "(8)":

.in +4

.sp

.B iptables

-t mangle -A POSTROUTING [...] -j CLASSIFY --set-class 0:4

.sp

.in -4

and this "4" priority can be used in the egress qos mapping to set

VLAN prio "5":

.sp

.in +4

.B ip

link set veth0.10 type vlan egress 4:5

.in -4

.in -4

.in -8

.TP

VXLAN Type Support

For a link of type

.I VXLAN

the following additional arguments are supported:

.BI "ip link add " DEVICE

.BI type " vxlan " id " VNI"

[

.BI dev " PHYS_DEV "

.RB " ] [ { " group " | " remote " } "

.I IPADDR

] [

.B local

.RI "{ "IPADDR " | "any " } "

] [

.BI ttl " TTL "

] [

.BI tos " TOS "

] [

.BI df " DF "

] [

.BI flowlabel " FLOWLABEL "

] [

.BI dstport " PORT "

] [

.BI srcport " MIN MAX "

] [

.RB [ no ] learning

] [

.RB [ no ] proxy

] [

.RB [ no ] rsc

] [

.RB [ no ] l2miss

] [

.RB [ no ] l3miss

] [

.RB [ no ] udpcsum

] [

.RB [ no ] udp6zerocsumtx

] [

.RB [ no ] udp6zerocsumrx

] [

.BI ageing " SECONDS "

] [

.BI maxaddress " NUMBER "

] [

.RB [ no ] external

] [

.B gbp

] [

.B gpe

]

.in +8

.sp

.BI  id " VNI "

- specifies the VXLAN Network Identifer (or VXLAN Segment

Identifier) to use.

.BI dev " PHYS_DEV"

- specifies the physical device to use for tunnel endpoint communication.

.sp

.BI group " IPADDR"

- specifies the multicast IP address to join.

This parameter cannot be specified with the

.B remote

parameter.

.sp

.BI remote " IPADDR"

- specifies the unicast destination IP address to use in outgoing packets

when the destination link layer address is not known in the VXLAN device

forwarding database. This parameter cannot be specified with the

.B group

parameter.

.sp

.BI local " IPADDR"

- specifies the source IP address to use in outgoing packets.

.sp

.BI ttl " TTL"

- specifies the TTL value to use in outgoing packets.

.sp

.BI tos " TOS"

- specifies the TOS value to use in outgoing packets.

.sp

.BI df " DF"

- specifies the usage of the Don't Fragment flag (DF) bit in outgoing packets

with IPv4 headers. The value

.B inherit

causes the bit to be copied from the original IP header. The values

.B unset

and

.B set

cause the bit to be always unset or always set, respectively. By default, the

bit is not set.

.sp

.BI flowlabel " FLOWLABEL"

- specifies the flow label to use in outgoing packets.

.sp

.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.

.sp

.RB [ no ] learning

- specifies if unknown source link layer addresses and IP addresses

are entered into the VXLAN device forwarding database.

.sp

.RB [ no ] rsc

- specifies if route short circuit is turned on.

.sp

.RB [ no ] proxy

- specifies ARP proxy is turned on.

.sp

.RB [ no ] l2miss

- specifies if netlink LLADDR miss notifications are generated.

.sp

.RB [ no ] l3miss

- specifies if netlink IP ADDR miss notifications are generated.

.sp

.RB [ no ] udpcsum

- specifies if UDP checksum is calculated for transmitted packets over IPv4.

.sp

.RB [ no ] udp6zerocsumtx

- skip UDP checksum calculation for transmitted packets over IPv6.

.sp

.RB [ no ] udp6zerocsumrx

- allow incoming UDP packets over IPv6 with zero checksum field.

.sp

.BI ageing " SECONDS"

- specifies the lifetime in seconds of FDB entries learnt by the kernel.

.sp

.BI maxaddress " NUMBER"

- specifies the maximum number of FDB entries.

.sp

.RB [ no ] external

- specifies whether an external control plane

.RB "(e.g. " "ip route encap" )

or the internal FDB should be used.

.sp

.B gbp

- enables the Group Policy extension (VXLAN-GBP).

.in +4

Allows to transport group policy context across VXLAN network peers.

If enabled, includes the mark of a packet in the VXLAN header for outgoing

packets and fills the packet mark based on the information found in the

VXLAN header for incoming packets.

Format of upper 16 bits of packet mark (flags);

.in +2

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

.br

|-|-|-|-|-|-|-|-|-|D|-|-|A|-|-|-|

.br

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

.B D :=

Don't Learn bit. When set, this bit indicates that the egress

VTEP MUST NOT learn the source address of the encapsulated frame.

.B A :=

Indicates that the group policy has already been applied to

this packet. Policies MUST NOT be applied by devices when the A bit is set.

.in -2

Format of lower 16 bits of packet mark (policy ID):

.in +2

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

.br

|        Group Policy ID        |

.br

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

.in -2

Example:

  iptables -A OUTPUT [...] -j MARK --set-mark 0x800FF

.in -4

.sp

.B gpe

- enables the Generic Protocol extension (VXLAN-GPE). Currently, this is

only supported together with the

.B external

keyword.

.in -8

.TP

VETH, VXCAN Type Support

For a link of types

.I VETH/VXCAN

the following additional arguments are supported:

.BI "ip link add " DEVICE

.BR type " { " veth " | " vxcan " }"

[

.BR peer

.BI "name " NAME

]

.in +8

.sp

.BR peer

.BI "name " NAME

- specifies the virtual pair device name of the

.I VETH/VXCAN

tunnel.

.in -8

.TP

IPIP, SIT Type Support

For a link of type

.IR IPIP or SIT

the following additional arguments are supported:

.BI "ip link add " DEVICE

.BR type " { " ipip " | " sit " }"

.BI " remote " ADDR " local " ADDR

[

.BR encap " { " fou " | " gue " | " none " }"

] [

.BR encap-sport " { " \fIPORT " | " auto " }"

] [

.BI "encap-dport " PORT

] [

.RB [ no ] encap-csum

] [

.I " [no]encap-remcsum "

] [

.I " mode " { ip6ip | ipip | mplsip | any } "

] [

.BR external

]

.in +8

.sp

.BI  remote " ADDR "

- specifies the remote address of the tunnel.

.sp

.BI  local " ADDR "

- specifies the fixed local address for tunneled packets.

It must be an address on another interface on this host.

.sp

.BR encap " { " fou " | " gue " | " none " }"

- specifies type of secondary UDP encapsulation. "fou" indicates

Foo-Over-UDP, "gue" indicates Generic UDP Encapsulation.

.sp

.BR encap-sport " { " \fIPORT " | " auto " }"

- specifies the source port in UDP encapsulation.

.IR PORT

indicates the port by number, "auto"

indicates that the port number should be chosen automatically

(the kernel picks a flow based on the flow hash of the

encapsulated packet).

.sp

.RB [ no ] encap-csum

- specifies if UDP checksums are enabled in the secondary

encapsulation.

.sp

.RB [ no ] encap-remcsum

- specifies if Remote Checksum Offload is enabled. This is only

applicable for Generic UDP Encapsulation.

.sp

.BI mode " { ip6ip | ipip | mplsip | any } "

- specifies mode in which device should run. "ip6ip" indicates

IPv6-Over-IPv4, "ipip" indicates "IPv4-Over-IPv4", "mplsip" indicates

MPLS-Over-IPv4, "any" indicates IPv6, IPv4 or MPLS Over IPv4. Supported for

SIT where the default is "ip6ip" and IPIP where the default is "ipip".

IPv6-Over-IPv4 is not supported for IPIP.

.sp

.BR external

- make this tunnel externally controlled

.RB "(e.g. " "ip route encap" ).

.in -8

.TP

GRE Type Support

For a link of type

.IR GRE " or " GRETAP

the following additional arguments are supported:

.BI "ip link add " DEVICE

.BR type " { " gre " | " gretap " }"

.BI " remote " ADDR " local " ADDR

[

.RB [ no ] "" [ i | o ] seq

] [

.RB [ i | o ] key

.I KEY

|

.BR no [ i | o ] key

] [

.RB [ no ] "" [ i | o ] csum

] [

.BI ttl " TTL "

] [

.BI tos " TOS "

] [

.RB [ no ] pmtudisc

] [

.RB [ no ] ignore-df

] [

.BI dev " PHYS_DEV "

] [

.BR encap " { " fou " | " gue " | " none " }"

] [

.BR encap-sport " { " \fIPORT " | " auto " }"

] [

.BI "encap-dport " PORT

] [

.RB [ no ] encap-csum

] [

.RB [ no ] encap-remcsum

] [

.BR external

]

.in +8

.sp

.BI  remote " ADDR "

- specifies the remote address of the tunnel.

.sp

.BI  local " ADDR "

- specifies the fixed local address for tunneled packets.

It must be an address on another interface on this host.