man/man8/ip-link.8.in

   1 .TH IP\-LINK 8 "13 Dec 2012" "iproute2" "Linux"
   2 .SH "NAME"
   3 ip-link \- network device configuration
   4 .SH "SYNOPSIS"
   5 .sp
   6 .ad l
   7 .in +8
   8 .ti -8
   9 .B ip link
  10 .RI  " { " COMMAND " | "
  11 .BR help " }"
  12 .sp
  13
  14 .ti -8
  15 .BI "ip link add"
  16 .RB "[ " link
  17 .IR DEVICE " ]"
  18 .RB "[ " name " ]"
  19 .I NAME
  20 .br
  21 .RB "[ " txqueuelen
  22 .IR PACKETS " ]"
  23 .br
  24 .RB "[ " address
  25 .IR LLADDR " ]"
  26 .RB "[ " broadcast
  27 .IR LLADDR " ]"
  28 .br
  29 .RB "[ " mtu
  30 .IR MTU " ]"
  31 .RB "[ " index
  32 .IR IDX " ]"
  33 .br
  34 .RB "[ " numtxqueues
  35 .IR QUEUE_COUNT " ]"
  36 .RB "[ " numrxqueues
  37 .IR QUEUE_COUNT " ]"
  38 .br
  39 .BI type " TYPE"
  40 .RI "[ " ARGS " ]"
  41
  42 .ti -8
  43 .BR "ip link delete " {
  44 .IR DEVICE " | "
  45 .BI "group " GROUP
  46 }
  47 .BI type " TYPE"
  48 .RI "[ " ARGS " ]"
  49
  50 .ti -8
  51 .BR "ip link set " {
  52 .IR DEVICE " | "
  53 .BI "group " GROUP
  54 }
  55 .br
  56 .RB "[ { " up " | " down " } ]"
  57 .br
  58 .RB "[ " type
  59 .IR "ETYPE TYPE_ARGS" " ]"
  60 .br
  61 .RB "[ " arp " { " on " | " off " } ]"
  62 .br
  63 .RB "[ " dynamic " { " on " | " off " } ]"
  64 .br
  65 .RB "[ " multicast " { " on " | " off " } ]"
  66 .br
  67 .RB "[ " allmulticast " { " on " | " off " } ]"
  68 .br
  69 .RB "[ " promisc " { " on " | " off " } ]"
  70 .br
  71 .RB "[ " protodown " { " on " | " off " } ]"
  72 .br
  73 .RB "[ " trailers " { " on " | " off " } ]"
  74 .br
  75 .RB "[ " txqueuelen
  76 .IR PACKETS " ]"
  77 .br
  78 .RB "[ " name
  79 .IR NEWNAME " ]"
  80 .br
  81 .RB "[ " address
  82 .IR LLADDR " ]"
  83 .br
  84 .RB "[ " broadcast
  85 .IR LLADDR " ]"
  86 .br
  87 .RB "[ " mtu
  88 .IR MTU " ]"
  89 .br
  90 .RB "[ " netns " {"
  91 .IR PID " | " NETNSNAME " } ]"
  92 .br
  93 .RB "[ " link-netnsid
  94 .IR ID " ]"
  95 .br
  96 .RB "[ " alias
  97 .IR NAME  " ]"
  98 .br
  99 .RB "[ " vf
 100 .IR NUM " ["
 101 .B  mac
 102 .IR LLADDR " ]"
 103 .br
 104 .in +9
 105 .RB "[ " vlan
 106 .IR VLANID " [ "
 107 .B qos
 108 .IR VLAN-QOS " ] ]"
 109 .br
 110 .RB "[ " rate
 111 .IR TXRATE " ]"
 112 .br
 113 .RB "[ " max_tx_rate
 114 .IR TXRATE " ]"
 115 .br
 116 .RB "[ " min_tx_rate
 117 .IR TXRATE " ]"
 118 .br
 119 .RB "[ " spoofchk " { " on " | " off " } ]"
 120 .br
 121 .RB "[ " query_rss " { " on " | " off " } ]"
 122 .br
 123 .RB "[ " state " { " auto " | " enable " | " disable " } ]"
 124 .br
 125 .RB "[ " trust " { " on " | " off " } ]"
 126 .br
 127 .RB "[ " node_guid " eui64 ]"
 128 .br
 129 .RB "[ " port_guid " eui64 ] ]"
 130 .br
 131 .in -9
 132 .RB "[ " master
 133 .IR DEVICE " ]"
 134 .br
 135 .RB "[ " nomaster " ]"
 136 .br
 137 .RB "[ " vrf
 138 .IR NAME " ]"
 139 .br
 140 .RB "[ " addrgenmode " { " eui64 " | " none " | " stable_secret " | " random " } ]"
 141
 142
 143 .ti -8
 144 .B ip link show
 145 .RI "[ " DEVICE " | "
 146 .B group
 147 .IR GROUP " ] ["
 148 .BR up " ] ["
 149 .B master
 150 .IR DEVICE " ] ["
 151 .B type
 152 .IR ETYPE " ]"
 153 .B vrf
 154 .IR NAME " ]"
 155
 156 .ti -8
 157 .B ip link help
 158 .RI "[ " TYPE " ]"
 159
 160 .ti -8
 161 .IR TYPE " := [ "
 162 .BR bridge " | "
 163 .BR bond " | "
 164 .BR can " | "
 165 .BR dummy " | "
 166 .BR hsr " | "
 167 .BR ifb " | "
 168 .BR ipoib " |"
 169 .BR macvlan  " | "
 170 .BR macvtap  " | "
 171 .BR vcan " | "
 172 .BR veth " | "
 173 .BR vlan " | "
 174 .BR vxlan " |"
 175 .BR ip6tnl " |"
 176 .BR ipip " |"
 177 .BR sit " |"
 178 .BR gre " |"
 179 .BR gretap " |"
 180 .BR ip6gre " |"
 181 .BR ip6gretap " |"
 182 .BR vti " |"
 183 .BR nlmon " |"
 184 .BR ipvlan " |"
 185 .BR lowpan " |"
 186 .BR geneve " |"
 187 .BR vrf " |"
 188 .BR macsec " ]"
 189
 190 .ti -8
 191 .IR ETYPE " := [ " TYPE " |"
 192 .BR bridge_slave " | " bond_slave " ]"
 193
 194 .SH "DESCRIPTION"
 195 .SS ip link add - add virtual link
 196
 197 .TP
 198 .BI link " DEVICE "
 199 specifies the physical device to act operate on.
 200
 201 .I NAME
 202 specifies the name of the new virtual device.
 203
 204 .I TYPE
 205 specifies the type of the new device.
 206 .sp
 207 Link types:
 208
 209 .in +8
 210 .B bridge
 211 - Ethernet Bridge device
 212 .sp
 213 .B bond
 214 - Bonding device
 215 .B can
 216 - Controller Area Network interface
 217 .sp
 218 .B dummy
 219 - Dummy network interface
 220 .sp
 221 .B hsr
 222 - High-availability Seamless Redundancy device
 223 .sp
 224 .B ifb
 225 - Intermediate Functional Block device
 226 .sp
 227 .B ipoib
 228 - IP over Infiniband device
 229 .sp
 230 .B macvlan
 231 - Virtual interface base on link layer address (MAC)
 232 .sp
 233 .B macvtap
 234 - Virtual interface based on link layer address (MAC) and TAP.
 235 .sp
 236 .B vcan
 237 - Virtual Controller Area Network interface
 238 .sp
 239 .B veth
 240 - Virtual ethernet interface
 241 .sp
 242 .BR vlan
 243 - 802.1q tagged virtual LAN interface
 244 .sp
 245 .BR vxlan
 246 - Virtual eXtended LAN
 247 .sp
 248 .BR ip6tnl
 249 - Virtual tunnel interface IPv4|IPv6 over IPv6
 250 .sp
 251 .BR ipip
 252 - Virtual tunnel interface IPv4 over IPv4
 253 .sp
 254 .BR sit
 255 - Virtual tunnel interface IPv6 over IPv4
 256 .sp
 257 .BR gre
 258 - Virtual tunnel interface GRE over IPv4
 259 .sp
 260 .BR gretap
 261 - Virtual L2 tunnel interface GRE over IPv4
 262 .sp
 263 .BR ip6gre
 264 - Virtual tunnel interface GRE over IPv6
 265 .sp
 266 .BR ip6gretap
 267 - Virtual L2 tunnel interface GRE over IPv6
 268 .sp
 269 .BR vti
 270 - Virtual tunnel interface
 271 .sp
 272 .BR nlmon
 273 - Netlink monitoring device
 274 .sp
 275 .BR ipvlan
 276 - Interface for L3 (IPv6/IPv4) based VLANs
 277 .sp
 278 .BR lowpan
 279 - Interface for 6LoWPAN (IPv6) over IEEE 802.15.4 / Bluetooth
 280 .sp
 281 .BR geneve
 282 - GEneric NEtwork Virtualization Encapsulation
 283 .sp
 284 .BR macsec
 285 - Interface for IEEE 802.1AE MAC Security (MACsec)
 286 .sp
 287 .BR vrf
 288 - Interface for L3 VRF domains
 289 .in -8
 290
 291 .TP
 292 .BI numtxqueues " QUEUE_COUNT "
 293 specifies the number of transmit queues for new device.
 294
 295 .TP
 296 .BI numrxqueues " QUEUE_COUNT "
 297 specifies the number of receive queues for new device.
 298
 299 .TP
 300 .BI index " IDX "
 301 specifies the desired index of the new virtual device. The link creation fails, if the index is busy.
 302
 303 .TP
 304 VLAN Type Support
 305 For a link of type
 306 .I VLAN
 307 the following additional arguments are supported:
 308
 309 .BI "ip link add
 310 .BI link " DEVICE "
 311 .BI name " NAME "
 312 .B "type vlan"
 313 [
 314 .BI protocol " VLAN_PROTO "
 315 ]
 316 .BI id " VLANID "
 317 [
 318 .BR reorder_hdr " { " on " | " off " } "
 319 ]
 320 [
 321 .BR gvrp " { " on " | " off " } "
 322 ]
 323 [
 324 .BR mvrp " { " on " | " off " } "
 325 ]
 326 [
 327 .BR loose_binding " { " on " | " off " } "
 328 ]
 329 [
 330 .BI ingress-qos-map " QOS-MAP "
 331 ]
 332 [
 333 .BI egress-qos-map " QOS-MAP "
 334 ]
 335
 336 .in +8
 337 .sp
 338 .BI protocol " VLAN_PROTO "
 339 - either 802.1Q or 802.1ad.
 340
 341 .BI id " VLANID "
 342 - specifies the VLAN Identifer to use. Note that numbers with a leading " 0 " or " 0x " are interpreted as octal or hexadeimal, respectively.
 343
 344 .BR reorder_hdr " { " on " | " off " } "
 345 - specifies whether ethernet headers are reordered or not (default is
 346 .BR on ")."
 347
 348 .in +4
 349 If
 350 .BR reorder_hdr " is " on
 351 then VLAN header will be not inserted immediately but only before passing to the
 352 physical device (if this device does not support VLAN offloading), the similar
 353 on the RX direction - by default the packet will be untagged before being
 354 received by VLAN device. Reordering allows to accelerate tagging on egress and
 355 to hide VLAN header on ingress so the packet looks like regular Ethernet packet,
 356 at the same time it might be confusing for packet capture as the VLAN header
 357 does not exist within the packet.
 358
 359 VLAN offloading can be checked by
 360 .BR ethtool "(8):"
 361 .in +4
 362 .sp
 363 .B ethtool -k
 364 <phy_dev> |
 365 .RB grep " tx-vlan-offload"
 366 .sp
 367 .in -4
 368 where <phy_dev> is the physical device to which VLAN device is bound.
 369 .in -4
 370
 371 .BR gvrp " { " on " | " off " } "
 372 - specifies whether this VLAN should be registered using GARP VLAN Registration Protocol.
 373
 374 .BR mvrp " { " on " | " off " } "
 375 - specifies whether this VLAN should be registered using Multiple VLAN Registration Protocol.
 376
 377 .BR loose_binding " { " on " | " off " } "
 378 - specifies whether the VLAN device state is bound to the physical device state.
 379
 380 .BI ingress-qos-map " QOS-MAP "
 381 - defines a mapping of VLAN header prio field to the Linux internal packet
 382 priority on incoming frames. The format is FROM:TO with multiple mappings
 383 separated by spaces.
 384
 385 .BI egress-qos-map " QOS-MAP "
 386 - defines a mapping of Linux internal packet priority to VLAN header prio field
 387 but for outgoing frames. The format is the same as for ingress-qos-map.
 388 .in +4
 389
 390 Linux packet priority can be set by
 391 .BR iptables "(8)":
 392 .in +4
 393 .sp
 394 .B iptables
 395 -t mangle -A POSTROUTING [...] -j CLASSIFY --set-class 0:4
 396 .sp
 397 .in -4
 398 and this "4" priority can be used in the egress qos mapping to set VLAN prio "5":
 399 .sp
 400 .in +4
 401 .B ip
 402 link set veth0.10 type vlan egress 4:5
 403 .in -4
 404 .in -4
 405 .in -8
 406
 407 .TP
 408 VXLAN Type Support
 409 For a link of type
 410 .I VXLAN
 411 the following additional arguments are supported:
 412
 413 .BI "ip link add " DEVICE
 414 .BI type " vxlan " id " VNI"
 415 [
 416 .BI dev " PHYS_DEV "
 417 .RB " ] [ { " group " | " remote " } "
 418 .I IPADDR
 419 ] [
 420 .B local
 421 .RI "{ "IPADDR " | "any " } "
 422 ] [
 423 .BI ttl " TTL "
 424 ] [
 425 .BI tos " TOS "
 426 ] [
 427 .BI flowlabel " FLOWLABEL "
 428 ] [
 429 .BI dstport " PORT "
 430 ] [
 431 .BI srcport " MIN MAX "
 432 ] [
 433 .RB [ no ] learning
 434 ] [
 435 .RB [ no ] proxy
 436 ] [
 437 .RB [ no ] rsc
 438 ] [
 439 .RB [ no ] l2miss
 440 ] [
 441 .RB [ no ] l3miss
 442 ] [
 443 .RB [ no ] udpcsum
 444 ] [
 445 .RB [ no ] udp6zerocsumtx
 446 ] [
 447 .RB [ no ] udp6zerocsumrx
 448 ] [
 449 .BI ageing " SECONDS "
 450 ] [
 451 .BI maxaddress " NUMBER "
 452 ] [
 453 .RB [ no ] external
 454 ] [
 455 .B gbp
 456 ] [
 457 .B gpe
 458 ]
 459
 460 .in +8
 461 .sp
 462 .BI  id " VNI "
 463 - specifies the VXLAN Network Identifer (or VXLAN Segment
 464 Identifier) to use.
 465
 466 .BI dev " PHYS_DEV"
 467 - specifies the physical device to use for tunnel endpoint communication.
 468
 469 .sp
 470 .BI group " IPADDR"
 471 - specifies the multicast IP address to join.
 472 This parameter cannot be specified with the
 473 .B remote
 474 parameter.
 475
 476 .sp
 477 .BI remote " IPADDR"
 478 - specifies the unicast destination IP address to use in outgoing packets
 479 when the destination link layer address is not known in the VXLAN device
 480 forwarding database. This parameter cannot be specified with the
 481 .B group
 482 parameter.
 483
 484 .sp
 485 .BI local " IPADDR"
 486 - specifies the source IP address to use in outgoing packets.
 487
 488 .sp
 489 .BI ttl " TTL"
 490 - specifies the TTL value to use in outgoing packets.
 491
 492 .sp
 493 .BI tos " TOS"
 494 - specifies the TOS value to use in outgoing packets.
 495
 496 .sp
 497 .BI flowlabel " FLOWLABEL"
 498 - specifies the flow label to use in outgoing packets.
 499
 500 .sp
 501 .BI dstport " PORT"
 502 - specifies the UDP destination port to communicate to the remote VXLAN tunnel endpoint.
 503
 504 .sp
 505 .BI srcport " MIN MAX"
 506 - specifies the range of port numbers to use as UDP
 507 source ports to communicate to the remote VXLAN tunnel endpoint.
 508
 509 .sp
 510 .RB [ no ] learning
 511 - specifies if unknown source link layer addresses and IP addresses
 512 are entered into the VXLAN device forwarding database.
 513
 514 .sp
 515 .RB [ no ] rsc
 516 - specifies if route short circuit is turned on.
 517
 518 .sp
 519 .RB [ no ] proxy
 520 - specifies ARP proxy is turned on.
 521
 522 .sp
 523 .RB [ no ] l2miss
 524 - specifies if netlink LLADDR miss notifications are generated.
 525
 526 .sp
 527 .RB [ no ] l3miss
 528 - specifies if netlink IP ADDR miss notifications are generated.
 529
 530 .sp
 531 .RB [ no ] udpcsum
 532 - specifies if UDP checksum is calculated for transmitted packets over IPv4.
 533
 534 .sp
 535 .RB [ no ] udp6zerocsumtx
 536 - skip UDP checksum calculation for transmitted packets over IPv6.
 537
 538 .sp
 539 .RB [ no ] udp6zerocsumrx
 540 - allow incoming UDP packets over IPv6 with zero checksum field.
 541
 542 .sp
 543 .BI ageing " SECONDS"
 544 - specifies the lifetime in seconds of FDB entries learnt by the kernel.
 545
 546 .sp
 547 .BI maxaddress " NUMBER"
 548 - specifies the maximum number of FDB entries.
 549
 550 .sp
 551 .RB [ no ] external
 552 - specifies whether an external control plane
 553 .RB "(e.g. " "ip route encap" )
 554 or the internal FDB should be used.
 555
 556 .sp
 557 .B gbp
 558 - enables the Group Policy extension (VXLAN-GBP).
 559
 560 .in +4
 561 Allows to transport group policy context across VXLAN network peers.
 562 If enabled, includes the mark of a packet in the VXLAN header for outgoing
 563 packets and fills the packet mark based on the information found in the
 564 VXLAN header for incomming packets.
 565
 566 Format of upper 16 bits of packet mark (flags);
 567
 568 .in +2
 569 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 570 .br
 571 |-|-|-|-|-|-|-|-|-|D|-|-|A|-|-|-|
 572 .br
 573 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 574
 575 .B D :=
 576 Don't Learn bit. When set, this bit indicates that the egress
 577 VTEP MUST NOT learn the source address of the encapsulated frame.
 578
 579 .B A :=
 580 Indicates that the group policy has already been applied to
 581 this packet. Policies MUST NOT be applied by devices when the A bit is set.
 582 .in -2
 583
 584 Format of lower 16 bits of packet mark (policy ID):
 585
 586 .in +2
 587 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 588 .br
 589 |        Group Policy ID        |
 590 .br
 591 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 592 .in -2
 593
 594 Example:
 595   iptables -A OUTPUT [...] -j MARK --set-mark 0x800FF
 596
 597 .in -4
 598
 599 .sp
 600 .B gpe
 601 - enables the Generic Protocol extension (VXLAN-GPE). Currently, this is
 602 only supported together with the
 603 .B external
 604 keyword.
 605
 606 .in -8
 607
 608 .TP
 609 GRE, IPIP, SIT Type Support
 610 For a link of types
 611 .I GRE/IPIP/SIT
 612 the following additional arguments are supported:
 613
 614 .BI "ip link add " DEVICE
 615 .BR type " { " gre " | " ipip " | " sit " }"
 616 .BI " remote " ADDR " local " ADDR
 617 [
 618 .BR encap " { " fou " | " gue " | " none " }"
 619 ] [
 620 .BR encap-sport " { " \fIPORT " | " auto " }"
 621 ] [
 622 .BI "encap-dport " PORT
 623 ] [
 624 .RB [ no ] encap-csum
 625 ] [
 626 .RB [ no ] encap-remcsum
 627 ]
 628
 629 .in +8
 630 .sp
 631 .BI  remote " ADDR "
 632 - specifies the remote address of the tunnel.
 633
 634 .sp
 635 .BI  local " ADDR "
 636 - specifies the fixed local address for tunneled packets.
 637 It must be an address on another interface on this host.
 638
 639 .sp
 640 .BR encap " { " fou " | " gue " | " none " }"
 641 - specifies type of secondary UDP encapsulation. "fou" indicates
 642 Foo-Over-UDP, "gue" indicates Generic UDP Encapsulation.
 643
 644 .sp
 645 .BR encap-sport " { " \fIPORT " | " auto " }"
 646 - specifies the source port in UDP encapsulation.
 647 .IR PORT
 648 indicates the port by number, "auto"
 649 indicates that the port number should be chosen automatically
 650 (the kernel picks a flow based on the flow hash of the
 651 encapsulated packet).
 652
 653 .sp
 654 .RB [ no ] encap-csum
 655 - specifies if UDP checksums are enabled in the secondary
 656 encapsulation.
 657
 658 .sp
 659 .RB [ no ] encap-remcsum
 660 - specifies if Remote Checksum Offload is enabled. This is only
 661 applicable for Generic UDP Encapsulation.
 662
 663 .in -8
 664
 665 .TP
 666 IP6GRE/IP6GRETAP Type Support
 667 For a link of type
 668 .I IP6GRE/IP6GRETAP
 669 the following additional arguments are supported:
 670
 671 .BI "ip link add " DEVICE
 672 .BR type " { " ip6gre " | " ip6gretap " }"
 673 .BI remote " ADDR " local " ADDR"
 674 [
 675 .RB [ i | o ] seq
 676 ] [
 677 .RB [ i | o ] key
 678 .I KEY
 679 ] [
 680 .RB [ i | o ] csum
 681 ] [
 682 .BI hoplimit " TTL "
 683 ] [
 684 .BI encaplimit " ELIM "
 685 ] [
 686 .BI tclass " TCLASS "
 687 ] [
 688 .BI flowlabel " FLOWLABEL "
 689 ] [
 690 .BI "dscp inherit"
 691 ] [
 692 .BI dev " PHYS_DEV "
 693 ]
 694
 695 .in +8
 696 .sp
 697 .BI  remote " ADDR "
 698 - specifies the remote IPv6 address of the tunnel.
 699
 700 .sp
 701 .BI  local " ADDR "
 702 - specifies the fixed local IPv6 address for tunneled packets.
 703 It must be an address on another interface on this host.
 704
 705 .sp
 706 .RB  [ i | o ] seq
 707 - serialize packets.
 708 The
 709 .B oseq
 710 flag enables sequencing of outgoing packets.
 711 The
 712 .B iseq
 713 flag requires that all input packets are serialized.
 714
 715 .sp
 716 .RB  [ i | o ] key " \fIKEY"
 717 - use keyed GRE with key
 718 .IR KEY ". "KEY
 719 is either a number or an IPv4 address-like dotted quad.
 720 The
 721 .B key
 722 parameter specifies the same key to use in both directions.
 723 The
 724 .BR ikey " and " okey
 725 parameters specify different keys for input and output.
 726
 727 .sp
 728 .RB  [ i | o ] csum
 729 - generate/require checksums for tunneled packets.
 730 The
 731 .B ocsum
 732 flag calculates checksums for outgoing packets.
 733 The
 734 .B icsum
 735 flag requires that all input packets have the correct
 736 checksum. The
 737 .B csum
 738 flag is equivalent to the combination
 739 .BR "icsum ocsum" .
 740
 741 .sp
 742 .BI  hoplimit " TTL"
 743 - specifies Hop Limit value to use in outgoing packets.
 744
 745 .sp
 746 .BI  encaplimit " ELIM"
 747 - specifies a fixed encapsulation limit. Default is 4.
 748
 749 .sp
 750 .BI  flowlabel " FLOWLABEL"
 751 - specifies a fixed flowlabel.
 752
 753 .sp
 754 .BI  tclass " TCLASS"
 755 - specifies the traffic class field on
 756 tunneled packets, which can be specified as either a two-digit
 757 hex value (e.g. c0) or a predefined string (e.g. internet).
 758 The value
 759 .B inherit
 760 causes the field to be copied from the original IP header. The
 761 values
 762 .BI "inherit/" STRING
 763 or
 764 .BI "inherit/" 00 ".." ff
 765 will set the field to
 766 .I STRING
 767 or
 768 .IR 00 ".." ff
 769 when tunneling non-IP packets. The default value is 00.
 770
 771 .in -8
 772
 773 .TP
 774 IPoIB Type Support
 775 For a link of type
 776 .I IPoIB
 777 the following additional arguments are supported:
 778
 779 .BI "ip link add " DEVICE " name " NAME
 780 .BR "type ipoib " [ " pkey \fIPKEY" " ] [ " mode " \fIMODE \fR]"
 781
 782 .in +8
 783 .sp
 784 .BI  pkey " PKEY "
 785 - specifies the IB P-Key to use.
 786
 787 .BI  mode " MODE "
 788 - specifies the mode (datagram or connected) to use.
 789
 790 .TP
 791 GENEVE Type Support
 792 For a link of type
 793 .I GENEVE
 794 the following additional arguments are supported:
 795
 796 .BI "ip link add " DEVICE
 797 .BI type " geneve " id " VNI " remote " IPADDR"
 798 [
 799 .BI ttl " TTL "
 800 ] [
 801 .BI tos " TOS "
 802 ] [
 803 .BI flowlabel " FLOWLABEL "
 804 ]
 805
 806 .in +8
 807 .sp
 808 .BI  id " VNI "
 809 - specifies the Virtual Network Identifer to use.
 810
 811 .sp
 812 .BI remote " IPADDR"
 813 - specifies the unicast destination IP address to use in outgoing packets.
 814
 815 .sp
 816 .BI ttl " TTL"
 817 - specifies the TTL value to use in outgoing packets.
 818
 819 .sp
 820 .BI tos " TOS"
 821 - specifies the TOS value to use in outgoing packets.
 822
 823 .sp
 824 .BI flowlabel " FLOWLABEL"
 825 - specifies the flow label to use in outgoing packets.
 826
 827 .in -8
 828
 829 .TP
 830 MACVLAN and MACVTAP Type Support
 831 For a link of type
 832 .I MACVLAN
 833 or
 834 .I MACVTAP
 835 the following additional arguments are supported:
 836
 837 .BI "ip link add link " DEVICE " name " NAME
 838 .BR type " { " macvlan " | " macvtap " } "
 839 .BR mode " { " private " | " vepa " | " bridge " | " passthru
 840 .RB " [ " nopromisc " ] } "
 841
 842 .in +8
 843 .sp
 844 .BR type " { " macvlan " | " macvtap " } "
 845 - specifies the link type to use.
 846 .BR macvlan " creates just a virtual interface, while "
 847 .BR macvtap " in addition creates a character device "
 848 .BR /dev/tapX " to be used just like a " tuntap " device."
 849
 850 .B mode private
 851 - Do not allow communication between
 852 .B macvlan
 853 instances on the same physical interface, even if the external switch supports
 854 hairpin mode.
 855
 856 .B mode vepa
 857 - Virtual Ethernet Port Aggregator mode. Data from one
 858 .B macvlan
 859 instance to the other on the same physical interface is transmitted over the
 860 physical interface. Either the attached switch needs to support hairpin mode,
 861 or there must be a TCP/IP router forwarding the packets in order to allow
 862 communication. This is the default mode.
 863
 864 .B mode bridge
 865 - In bridge mode, all endpoints are directly connected to each other,
 866 communication is not redirected through the physical interface's peer.
 867
 868 .BR mode " " passthru " [ " nopromisc " ] "
 869 - This mode gives more power to a single endpoint, usually in
 870 .BR macvtap " mode. It is not allowed for more than one endpoint on the same "
 871 physical interface. All traffic will be forwarded to this endpoint, allowing
 872 virtio guests to change MAC address or set promiscuous mode in order to bridge
 873 the interface or create vlan interfaces on top of it. By default, this mode
 874 forces the underlying interface into promiscuous mode. Passing the
 875 .BR nopromisc " flag prevents this, so the promisc flag may be controlled "
 876 using standard tools.
 877 .in -8
 878
 879 .TP
 880 High-availability Seamless Redundancy (HSR) Support
 881 For a link of type
 882 .I HSR
 883 the following additional arguments are supported:
 884
 885 .BI "ip link add link " DEVICE " name " NAME " type hsr"
 886 .BI slave1 " SLAVE1-IF " slave2 " SLAVE2-IF "
 887 .RB [ " supervision"
 888 .IR ADDR-BYTE " ] ["
 889 .BR version " { " 0 " | " 1 " } ]"
 890
 891 .in +8
 892 .sp
 893 .BR type " hsr "
 894 - specifies the link type to use, here HSR.
 895
 896 .BI slave1 " SLAVE1-IF "
 897 - Specifies the physical device used for the first of the two ring ports.
 898
 899 .BI slave2 " SLAVE2-IF "
 900 - Specifies the physical device used for the second of the two ring ports.
 901
 902 .BI supervision " ADDR-BYTE"
 903 - The last byte of the multicast address used for HSR supervision frames.
 904 Default option is "0", possible values 0-255.
 905
 906 .BR version " { " 0 " | " 1 " }"
 907 - Selects the protocol version of the interface. Default option is "0", which
 908 corresponds to the 2010 version of the HSR standard. Option "1" activates the
 909 2012 version.
 910 .in -8
 911
 912 .TP
 913 MACsec Type Support
 914 For a link of type
 915 .I MACsec
 916 the following additional arguments are supported:
 917
 918 .BI "ip link add link " DEVICE " name " NAME " type macsec"
 919 [
 920 .BI port " PORT"
 921 |
 922 .BI sci " SCI"
 923 ] [
 924 .BI cipher " CIPHER_SUITE"
 925 ] [
 926 .BR encrypt " {"
 927 .BR on " | " off " } ] [ "
 928 .BR send_sci " { " on " | " off " } ] ["
 929 .BR end_station " { " on " | " off " } ] ["
 930 .BR scb " { " on " | " off " } ] ["
 931 .BR protect " { " on " | " off " } ] ["
 932 .BR replay " { " on " | " off " }"
 933 .BR window " { "
 934 .IR 0..2^32-1 " } ] ["
 935 .BR validate " { " strict " | " check " | " disabled " } ] ["
 936 .BR encodingsa " { "
 937 .IR 0..3 " } ]"
 938
 939 .in +8
 940 .sp
 941 .BI  port " PORT "
 942 - sets the port number for this MACsec device.
 943
 944 .sp
 945 .BI sci " SCI "
 946 - sets the SCI for this MACsec device.
 947
 948 .sp
 949 .BI cipher " CIPHER_SUITE "
 950 - defines the cipher suite to use.
 951
 952 .sp
 953 .BR "encrypt on " or " encrypt off"
 954 - switches between authenticated encryption, or authenticity mode only.
 955
 956 .sp
 957 .BR "send_sci on " or " send_sci off"
 958 - specifies whether the SCI is included in every packet, or only when it is necessary.
 959
 960 .sp
 961 .BR "end_station on " or " end_station off"
 962 - sets the End Station bit.
 963
 964 .sp
 965 .BR "scb on " or " scb off"
 966 - sets the Single Copy Broadcast bit.
 967
 968 .sp
 969 .BR "protect on " or " protect off"
 970 - enables MACsec protection on the device.
 971
 972 .sp
 973 .BR "replay on " or " replay off"
 974 - enables replay protection on the device.
 975
 976 .in +8
 977
 978 .sp
 979 .BI window " SIZE "
 980 - sets the size of the replay window.
 981
 982 .in -8
 983
 984 .sp
 985 .BR "validate strict " or " validate check " or " validate disabled"
 986 - sets the validation mode on the device.
 987
 988 .sp
 989 .BI encodingsa " AN "
 990 - sets the active secure association for transmission.
 991
 992 .in -8
 993
 994 .TP
 995 VRF Type Support
 996 For a link of type
 997 .I VRF
 998 the following additional arguments are supported:
 999
1000 .BI "ip link add " DEVICE " type vrf table " TABLE
1001
1002 .in +8
1003 .sp
1004 .BR table " table id associated with VRF device"
1005
1006 .in -8
1007
1008 .SS ip link delete - delete virtual link
1009
1010 .TP
1011 .BI dev " DEVICE "
1012 specifies the virtual device to act operate on.
1013
1014 .TP
1015 .BI group " GROUP "
1016 specifies the group of virtual links to delete. Group 0 is not allowed to be
1017 deleted since it is the default group.
1018
1019 .TP
1020 .BI type " TYPE "
1021 specifies the type of the device.
1022
1023 .SS ip link set - change device attributes
1024
1025 .PP
1026 .B Warning:
1027 If multiple parameter changes are requested,
1028 .B ip
1029 aborts immediately after any of the changes have failed.
1030 This is the only case when
1031 .B ip
1032 can move the system to an unpredictable state. The solution
1033 is to avoid changing several parameters with one
1034 .B ip link set
1035 call.
1036
1037 .TP
1038 .BI dev " DEVICE "
1039 .I DEVICE
1040 specifies network device to operate on. When configuring SR-IOV Virtual Function
1041 (VF) devices, this keyword should specify the associated Physical Function (PF)
1042 device.
1043
1044 .TP
1045 .BI group " GROUP "
1046 .I GROUP
1047 has a dual role: If both group and dev are present, then move the device to the
1048 specified group. If only a group is specified, then the command operates on
1049 all devices in that group.
1050
1051 .TP
1052 .BR up " and " down
1053 change the state of the device to
1054 .B UP
1055 or
1056 .BR "DOWN" .
1057
1058 .TP
1059 .BR "arp on " or " arp off"
1060 change the
1061 .B NOARP
1062 flag on the device.
1063
1064 .TP
1065 .BR "multicast on " or " multicast off"
1066 change the
1067 .B MULTICAST
1068 flag on the device.
1069
1070 .TP
1071 .BR "protodown on " or " protodown off"
1072 change the
1073 .B PROTODOWN
1074 state on the device. Indicates that a protocol error has been detected on the port. Switch drivers can react to this error by doing a phys down on the switch port.
1075
1076 .TP
1077 .BR "dynamic on " or " dynamic off"
1078 change the
1079 .B DYNAMIC
1080 flag on the device. Indicates that address can change when interface goes down (currently
1081 .B NOT
1082 used by the Linux).
1083
1084 .TP
1085 .BI name " NAME"
1086 change the name of the device. This operation is not
1087 recommended if the device is running or has some addresses
1088 already configured.
1089
1090 .TP
1091 .BI txqueuelen " NUMBER"
1092 .TP
1093 .BI txqlen " NUMBER"
1094 change the transmit queue length of the device.
1095
1096 .TP
1097 .BI mtu " NUMBER"
1098 change the
1099 .I MTU
1100 of the device.
1101
1102 .TP
1103 .BI address " LLADDRESS"
1104 change the station address of the interface.
1105
1106 .TP
1107 .BI broadcast " LLADDRESS"
1108 .TP
1109 .BI brd " LLADDRESS"
1110 .TP
1111 .BI peer " LLADDRESS"
1112 change the link layer broadcast address or the peer address when
1113 the interface is
1114 .IR "POINTOPOINT" .
1115
1116 .TP
1117 .BI netns " NETNSNAME " \fR| " PID"
1118 move the device to the network namespace associated with name
1119 .IR "NETNSNAME " or
1120 .RI process " PID".
1121
1122 Some devices are not allowed to change network namespace: loopback, bridge,
1123 ppp, wireless. These are network namespace local devices. In such case
1124 .B ip
1125 tool will return "Invalid argument" error. It is possible to find out if device is local
1126 to a single network namespace by checking
1127 .B netns-local
1128 flag in the output of the
1129 .BR ethtool ":"
1130
1131 .in +8
1132 .B ethtool -k
1133 .I DEVICE
1134 .in -8
1135
1136 To change network namespace for wireless devices the
1137 .B iw
1138 tool can be used. But it allows to change network namespace only for physical devices and by process
1139 .IR PID .
1140
1141 .TP
1142 .BI alias " NAME"
1143 give the device a symbolic name for easy reference.
1144
1145 .TP
1146 .BI group " GROUP"
1147 specify the group the device belongs to.
1148 The available groups are listed in file
1149 .BR "@SYSCONFDIR@/group" .
1150
1151 .TP
1152 .BI vf " NUM"
1153 specify a Virtual Function device to be configured. The associated PF device
1154 must be specified using the
1155 .B dev
1156 parameter.
1157
1158 .in +8
1159 .BI mac " LLADDRESS"
1160 - change the station address for the specified VF. The
1161 .B vf
1162 parameter must be specified.
1163
1164 .sp
1165 .BI vlan " VLANID"
1166 - change the assigned VLAN for the specified VF. When specified, all traffic
1167 sent from the VF will be tagged with the specified VLAN ID. Incoming traffic
1168 will be filtered for the specified VLAN ID, and will have all VLAN tags
1169 stripped before being passed to the VF. Setting this parameter to 0 disables
1170 VLAN tagging and filtering. The
1171 .B vf
1172 parameter must be specified.
1173
1174 .sp
1175 .BI qos " VLAN-QOS"
1176 - assign VLAN QOS (priority) bits for the VLAN tag. When specified, all VLAN
1177 tags transmitted by the VF will include the specified priority bits in the
1178 VLAN tag. If not specified, the value is assumed to be 0. Both the
1179 .B vf
1180 and
1181 .B vlan
1182 parameters must be specified. Setting both
1183 .B vlan
1184 and
1185 .B qos
1186 as 0 disables VLAN tagging and filtering for the VF.
1187
1188 .sp
1189 .BI rate " TXRATE"
1190 -- change the allowed transmit bandwidth, in Mbps, for the specified VF.
1191 Setting this parameter to 0 disables rate limiting.
1192 .B vf
1193 parameter must be specified.
1194 Please use new API
1195 .B "max_tx_rate"
1196 option instead.
1197
1198 .sp
1199 .BI max_tx_rate " TXRATE"
1200 - change the allowed maximum transmit bandwidth, in Mbps, for the specified VF.
1201 .B vf
1202 parameter must be specified.
1203
1204 .sp
1205 .BI min_tx_rate " TXRATE"
1206 - change the allowed minimum transmit bandwidth, in Mbps, for the specified VF.
1207 Minimum TXRATE should be always <= Maximum TXRATE.
1208 .B vf
1209 parameter must be specified.
1210
1211 .sp
1212 .BI spoofchk " on|off"
1213 - turn packet spoof checking on or off for the specified VF.
1214 .sp
1215 .BI query_rss " on|off"
1216 - toggle the ability of querying the RSS configuration of a specific VF. VF RSS information like RSS hash key may be considered sensitive on some devices where this information is shared between VF and PF and thus its querying may be prohibited by default.
1217 .sp
1218 .BI state " auto|enable|disable"
1219 - set the virtual link state as seen by the specified VF. Setting to auto means a
1220 reflection of the PF link state, enable lets the VF to communicate with other VFs on
1221 this host even if the PF link state is down, disable causes the HW to drop any packets
1222 sent by the VF.
1223 .sp
1224 .BI trust " on|off"
1225 - trust the specified VF user. This enables that VF user can set a specific feature
1226 which may impact security and/or performance. (e.g. VF multicast promiscuous mode)
1227 .sp
1228 .BI node_guid " eui64"
1229 - configure node GUID for the VF.
1230 .sp
1231 .BI port_guid " eui64"
1232 - configure port GUID for the VF.
1233 .in -8
1234
1235 .TP
1236 .BI master " DEVICE"
1237 set master device of the device (enslave device).
1238
1239 .TP
1240 .BI nomaster
1241 unset master device of the device (release device).
1242
1243 .TP
1244 .BI addrgenmode " eui64|none|stable_secret|random"
1245 set the IPv6 address generation mode
1246
1247 .I eui64
1248 - use a Modified EUI-64 format interface identifier
1249
1250 .I none
1251 - disable automatic address generation
1252
1253 .I stable_secret
1254 - generate the interface identifier based on a preset /proc/sys/net/ipv6/conf/{default,DEVICE}/stable_secret
1255
1256 .I random
1257 - like stable_secret, but auto-generate a new random secret if none is set
1258
1259 .TP
1260 .BR "link-netnsid "
1261 set peer netnsid for a cross-netns interface
1262
1263 .TP
1264 .BI type " ETYPE TYPE_ARGS"
1265 Change type-specific settings. For a list of supported types and arguments refer
1266 to the description of
1267 .B "ip link add"
1268 above. In addition to that, it is possible to manipulate settings to slave
1269 devices:
1270
1271 .TP
1272 Bridge Slave Support
1273 For a link with master
1274 .B bridge
1275 the following additional arguments are supported:
1276
1277 .B "ip link set type bridge_slave"
1278 [
1279 .BI state " STATE"
1280 ] [
1281 .BI priority " PRIO"
1282 ] [
1283 .BI cost " COST"
1284 ] [
1285 .BR guard " { " on " | " off " }"
1286 ] [
1287 .BR hairpin " { " on " | " off " }"
1288 ] [
1289 .BR fastleave " { " on " | " off " }"
1290 ] [
1291 .BR root_block " { " on " | " off " }"
1292 ] [
1293 .BR learning " { " on " | " off " }"
1294 ] [
1295 .BR flood " { " on " | " off " }"
1296 ] [
1297 .BR proxy_arp " { " on " | " off " }"
1298 ] [
1299 .BR proxy_arp_wifi " { " on " | " off " }"
1300 ] [
1301 .BI mcast_router " MULTICAST_ROUTER"
1302 ] [
1303 .BR mcast_fast_leave " { " on " | " off "} ]"
1304
1305 .in +8
1306 .sp
1307 .BI state " STATE"
1308 - Set port state.
1309 .I STATE
1310 is a number representing the following states:
1311 .BR 0 " (disabled),"
1312 .BR 1 " (listening),"
1313 .BR 2 " (learning),"
1314 .BR 3 " (forwarding),"
1315 .BR 4 " (blocking)."
1316
1317 .BI priority " PRIO"
1318 - set port priority (a 16bit unsigned value).
1319
1320 .BI cost " COST"
1321 - set port cost (a 32bit unsigned value).
1322
1323 .BR guard " { " on " | " off " }"
1324 - block incoming BPDU packets on this port.
1325
1326 .BR hairpin " { " on " | " off " }"
1327 - enable hairpin mode on this port. This will allow incoming packets on this
1328 port to be reflected back.
1329
1330 .BR fastleave " { " on " | " off " }"
1331 - enable multicast fast leave on this port.
1332
1333 .BR root_block " { " on " | " off " }"
1334 - block this port from becoming the bridge's root port.
1335
1336 .BR learning " { " on " | " off " }"
1337 - allow MAC address learning on this port.
1338
1339 .BR flood " { " on " | " off " }"
1340 - open the flood gates on this port, i.e. forward all unicast frames to this
1341 port also. Requires
1342 .BR proxy_arp " and " proxy_arp_wifi
1343 to be turned off.
1344
1345 .BR proxy_arp " { " on " | " off " }"
1346 - enable proxy ARP on this port.
1347
1348 .BR proxy_arp_wifi " { " on " | " off " }"
1349 - enable proxy ARP on this port which meets extended requirements by IEEE
1350 802.11 and Hotspot 2.0 specifications.
1351
1352 .BI mcast_router " MULTICAST_ROUTER"
1353 - configure this port for having multicast routers attached. A port with a
1354 multicast router will receive all multicast traffic.
1355 .I MULTICAST_ROUTER
1356 may be either
1357 .B 0
1358 to disable multicast routers on this port,
1359 .B 1
1360 to let the system detect the presence of of routers (this is the default),
1361 .B 2
1362 to permanently enable multicast traffic forwarding on this port or
1363 .B 3
1364 to enable multicast routers temporarily on this port, not depending on incoming
1365 queries.
1366
1367 .BR mcast_fast_leave " { " on " | " off " }"
1368 - this is a synonym to the
1369 .B fastleave
1370 option above.
1371
1372 .in -8
1373
1374 .TP
1375 Bonding Slave Support
1376 For a link with master
1377 .B bond
1378 the following additional arguments are supported:
1379
1380 .B "ip link set type bond_slave"
1381 [
1382 .BI queue_id " ID"
1383 ]
1384
1385 .in +8
1386 .sp
1387 .BI queue_id " ID"
1388 - set the slave's queue ID (a 16bit unsigned value).
1389
1390 .in -8
1391
1392 .SS  ip link show - display device attributes
1393
1394 .TP
1395 .BI dev " NAME " (default)
1396 .I NAME
1397 specifies the network device to show.
1398 If this argument is omitted all devices in the default group are listed.
1399
1400 .TP
1401 .BI group " GROUP "
1402 .I GROUP
1403 specifies what group of devices to show.
1404
1405 .TP
1406 .B up
1407 only display running interfaces.
1408
1409 .TP
1410 .BI master " DEVICE "
1411 .I DEVICE
1412 specifies the master device which enslaves devices to show.
1413
1414 .TP
1415 .BI vrf " NAME "
1416 .I NAME
1417 speficies the VRF which enslaves devices to show.
1418
1419 .TP
1420 .BI type " TYPE "
1421 .I TYPE
1422 specifies the type of devices to show.
1423
1424 Note that the type name is not checked against the list of supported types -
1425 instead it is sent as-is to the kernel. Later it is used to filter the returned
1426 interface list by comparing it with the relevant attribute in case the kernel
1427 didn't filter already. Therefore any string is accepted, but may lead to empty
1428 output.
1429
1430 .SS  ip link help - display help
1431
1432 .PP
1433 .I "TYPE"
1434 specifies which help of link type to dislpay.
1435
1436 .SS
1437 .I GROUP
1438 may be a number or a string from the file
1439 .B @SYSCONFDIR@/group
1440 which can be manually filled.
1441
1442 .SH "EXAMPLES"
1443 .PP
1444 ip link show
1445 .RS 4
1446 Shows the state of all network interfaces on the system.
1447 .RE
1448 .PP
1449 ip link show type bridge
1450 .RS 4
1451 Shows the bridge devices.
1452 .RE
1453 .PP
1454 ip link show type vlan
1455 .RS 4
1456 Shows the vlan devices.
1457 .RE
1458 .PP
1459 ip link show master br0
1460 .RS 4
1461 Shows devices enslaved by br0
1462 .RE
1463 .PP
1464 ip link set dev ppp0 mtu 1400
1465 .RS 4
1466 Change the MTU the ppp0 device.
1467 .RE
1468 .PP
1469 ip link add link eth0 name eth0.10 type vlan id 10
1470 .RS 4
1471 Creates a new vlan device eth0.10 on device eth0.
1472 .RE
1473 .PP
1474 ip link delete dev eth0.10
1475 .RS 4
1476 Removes vlan device.
1477 .RE
1478
1479 ip link help gre
1480 .RS 4
1481 Display help for the gre link type.
1482 .RE
1483 .PP
1484 ip link add name tun1 type ipip remote 192.168.1.1
1485 local 192.168.1.2 ttl 225 encap gue encap-sport auto
1486 encap-dport 5555 encap-csum encap-remcsum
1487 .RS 4
1488 Creates an IPIP that is encapsulated with Generic UDP Encapsulation,
1489 and the outer UDP checksum and remote checksum offload are enabled.
1490
1491 .RE
1492 .PP
1493 ip link add link wpan0 lowpan0 type lowpan
1494 .RS 4
1495 Creates a 6LoWPAN interface named lowpan0 on the underlying
1496 IEEE 802.15.4 device wpan0.
1497 .RE
1498
1499 .SH SEE ALSO
1500 .br
1501 .BR ip (8),
1502 .BR ip-netns (8),
1503 .BR ethtool (8),
1504 .BR iptables (8)
1505
1506 .SH AUTHOR
1507 Original Manpage by Michail Litvak <mci@owl.openwall.com>