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 icvlen " { "
 927 .IR 8..16 " } ] ["
 928 .BR encrypt " {"
 929 .BR on " | " off " } ] [ "
 930 .BR send_sci " { " on " | " off " } ] ["
 931 .BR end_station " { " on " | " off " } ] ["
 932 .BR scb " { " on " | " off " } ] ["
 933 .BR protect " { " on " | " off " } ] ["
 934 .BR replay " { " on " | " off " }"
 935 .BR window " { "
 936 .IR 0..2^32-1 " } ] ["
 937 .BR validate " { " strict " | " check " | " disabled " } ] ["
 938 .BR encodingsa " { "
 939 .IR 0..3 " } ]"
 940
 941 .in +8
 942 .sp
 943 .BI  port " PORT "
 944 - sets the port number for this MACsec device.
 945
 946 .sp
 947 .BI sci " SCI "
 948 - sets the SCI for this MACsec device.
 949
 950 .sp
 951 .BI cipher " CIPHER_SUITE "
 952 - defines the cipher suite to use.
 953
 954 .sp
 955 .BI icvlen " LENGTH "
 956 - sets the length of the Integrity Check Value (ICV).
 957
 958 .sp
 959 .BR "encrypt on " or " encrypt off"
 960 - switches between authenticated encryption, or authenticity mode only.
 961
 962 .sp
 963 .BR "send_sci on " or " send_sci off"
 964 - specifies whether the SCI is included in every packet, or only when it is necessary.
 965
 966 .sp
 967 .BR "end_station on " or " end_station off"
 968 - sets the End Station bit.
 969
 970 .sp
 971 .BR "scb on " or " scb off"
 972 - sets the Single Copy Broadcast bit.
 973
 974 .sp
 975 .BR "protect on " or " protect off"
 976 - enables MACsec protection on the device.
 977
 978 .sp
 979 .BR "replay on " or " replay off"
 980 - enables replay protection on the device.
 981
 982 .in +8
 983
 984 .sp
 985 .BI window " SIZE "
 986 - sets the size of the replay window.
 987
 988 .in -8
 989
 990 .sp
 991 .BR "validate strict " or " validate check " or " validate disabled"
 992 - sets the validation mode on the device.
 993
 994 .sp
 995 .BI encodingsa " AN "
 996 - sets the active secure association for transmission.
 997
 998 .in -8
 999
1000 .TP
1001 VRF Type Support
1002 For a link of type
1003 .I VRF
1004 the following additional arguments are supported:
1005
1006 .BI "ip link add " DEVICE " type vrf table " TABLE
1007
1008 .in +8
1009 .sp
1010 .BR table " table id associated with VRF device"
1011
1012 .in -8
1013
1014 .SS ip link delete - delete virtual link
1015
1016 .TP
1017 .BI dev " DEVICE "
1018 specifies the virtual device to act operate on.
1019
1020 .TP
1021 .BI group " GROUP "
1022 specifies the group of virtual links to delete. Group 0 is not allowed to be
1023 deleted since it is the default group.
1024
1025 .TP
1026 .BI type " TYPE "
1027 specifies the type of the device.
1028
1029 .SS ip link set - change device attributes
1030
1031 .PP
1032 .B Warning:
1033 If multiple parameter changes are requested,
1034 .B ip
1035 aborts immediately after any of the changes have failed.
1036 This is the only case when
1037 .B ip
1038 can move the system to an unpredictable state. The solution
1039 is to avoid changing several parameters with one
1040 .B ip link set
1041 call.
1042
1043 .TP
1044 .BI dev " DEVICE "
1045 .I DEVICE
1046 specifies network device to operate on. When configuring SR-IOV Virtual Function
1047 (VF) devices, this keyword should specify the associated Physical Function (PF)
1048 device.
1049
1050 .TP
1051 .BI group " GROUP "
1052 .I GROUP
1053 has a dual role: If both group and dev are present, then move the device to the
1054 specified group. If only a group is specified, then the command operates on
1055 all devices in that group.
1056
1057 .TP
1058 .BR up " and " down
1059 change the state of the device to
1060 .B UP
1061 or
1062 .BR "DOWN" .
1063
1064 .TP
1065 .BR "arp on " or " arp off"
1066 change the
1067 .B NOARP
1068 flag on the device.
1069
1070 .TP
1071 .BR "multicast on " or " multicast off"
1072 change the
1073 .B MULTICAST
1074 flag on the device.
1075
1076 .TP
1077 .BR "protodown on " or " protodown off"
1078 change the
1079 .B PROTODOWN
1080 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.
1081
1082 .TP
1083 .BR "dynamic on " or " dynamic off"
1084 change the
1085 .B DYNAMIC
1086 flag on the device. Indicates that address can change when interface goes down (currently
1087 .B NOT
1088 used by the Linux).
1089
1090 .TP
1091 .BI name " NAME"
1092 change the name of the device. This operation is not
1093 recommended if the device is running or has some addresses
1094 already configured.
1095
1096 .TP
1097 .BI txqueuelen " NUMBER"
1098 .TP
1099 .BI txqlen " NUMBER"
1100 change the transmit queue length of the device.
1101
1102 .TP
1103 .BI mtu " NUMBER"
1104 change the
1105 .I MTU
1106 of the device.
1107
1108 .TP
1109 .BI address " LLADDRESS"
1110 change the station address of the interface.
1111
1112 .TP
1113 .BI broadcast " LLADDRESS"
1114 .TP
1115 .BI brd " LLADDRESS"
1116 .TP
1117 .BI peer " LLADDRESS"
1118 change the link layer broadcast address or the peer address when
1119 the interface is
1120 .IR "POINTOPOINT" .
1121
1122 .TP
1123 .BI netns " NETNSNAME " \fR| " PID"
1124 move the device to the network namespace associated with name
1125 .IR "NETNSNAME " or
1126 .RI process " PID".
1127
1128 Some devices are not allowed to change network namespace: loopback, bridge,
1129 ppp, wireless. These are network namespace local devices. In such case
1130 .B ip
1131 tool will return "Invalid argument" error. It is possible to find out if device is local
1132 to a single network namespace by checking
1133 .B netns-local
1134 flag in the output of the
1135 .BR ethtool ":"
1136
1137 .in +8
1138 .B ethtool -k
1139 .I DEVICE
1140 .in -8
1141
1142 To change network namespace for wireless devices the
1143 .B iw
1144 tool can be used. But it allows to change network namespace only for physical devices and by process
1145 .IR PID .
1146
1147 .TP
1148 .BI alias " NAME"
1149 give the device a symbolic name for easy reference.
1150
1151 .TP
1152 .BI group " GROUP"
1153 specify the group the device belongs to.
1154 The available groups are listed in file
1155 .BR "@SYSCONFDIR@/group" .
1156
1157 .TP
1158 .BI vf " NUM"
1159 specify a Virtual Function device to be configured. The associated PF device
1160 must be specified using the
1161 .B dev
1162 parameter.
1163
1164 .in +8
1165 .BI mac " LLADDRESS"
1166 - change the station address for the specified VF. The
1167 .B vf
1168 parameter must be specified.
1169
1170 .sp
1171 .BI vlan " VLANID"
1172 - change the assigned VLAN for the specified VF. When specified, all traffic
1173 sent from the VF will be tagged with the specified VLAN ID. Incoming traffic
1174 will be filtered for the specified VLAN ID, and will have all VLAN tags
1175 stripped before being passed to the VF. Setting this parameter to 0 disables
1176 VLAN tagging and filtering. The
1177 .B vf
1178 parameter must be specified.
1179
1180 .sp
1181 .BI qos " VLAN-QOS"
1182 - assign VLAN QOS (priority) bits for the VLAN tag. When specified, all VLAN
1183 tags transmitted by the VF will include the specified priority bits in the
1184 VLAN tag. If not specified, the value is assumed to be 0. Both the
1185 .B vf
1186 and
1187 .B vlan
1188 parameters must be specified. Setting both
1189 .B vlan
1190 and
1191 .B qos
1192 as 0 disables VLAN tagging and filtering for the VF.
1193
1194 .sp
1195 .BI rate " TXRATE"
1196 -- change the allowed transmit bandwidth, in Mbps, for the specified VF.
1197 Setting this parameter to 0 disables rate limiting.
1198 .B vf
1199 parameter must be specified.
1200 Please use new API
1201 .B "max_tx_rate"
1202 option instead.
1203
1204 .sp
1205 .BI max_tx_rate " TXRATE"
1206 - change the allowed maximum transmit bandwidth, in Mbps, for the specified VF.
1207 .B vf
1208 parameter must be specified.
1209
1210 .sp
1211 .BI min_tx_rate " TXRATE"
1212 - change the allowed minimum transmit bandwidth, in Mbps, for the specified VF.
1213 Minimum TXRATE should be always <= Maximum TXRATE.
1214 .B vf
1215 parameter must be specified.
1216
1217 .sp
1218 .BI spoofchk " on|off"
1219 - turn packet spoof checking on or off for the specified VF.
1220 .sp
1221 .BI query_rss " on|off"
1222 - 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.
1223 .sp
1224 .BI state " auto|enable|disable"
1225 - set the virtual link state as seen by the specified VF. Setting to auto means a
1226 reflection of the PF link state, enable lets the VF to communicate with other VFs on
1227 this host even if the PF link state is down, disable causes the HW to drop any packets
1228 sent by the VF.
1229 .sp
1230 .BI trust " on|off"
1231 - trust the specified VF user. This enables that VF user can set a specific feature
1232 which may impact security and/or performance. (e.g. VF multicast promiscuous mode)
1233 .sp
1234 .BI node_guid " eui64"
1235 - configure node GUID for the VF.
1236 .sp
1237 .BI port_guid " eui64"
1238 - configure port GUID for the VF.
1239 .in -8
1240
1241 .TP
1242 .BI master " DEVICE"
1243 set master device of the device (enslave device).
1244
1245 .TP
1246 .BI nomaster
1247 unset master device of the device (release device).
1248
1249 .TP
1250 .BI addrgenmode " eui64|none|stable_secret|random"
1251 set the IPv6 address generation mode
1252
1253 .I eui64
1254 - use a Modified EUI-64 format interface identifier
1255
1256 .I none
1257 - disable automatic address generation
1258
1259 .I stable_secret
1260 - generate the interface identifier based on a preset /proc/sys/net/ipv6/conf/{default,DEVICE}/stable_secret
1261
1262 .I random
1263 - like stable_secret, but auto-generate a new random secret if none is set
1264
1265 .TP
1266 .BR "link-netnsid "
1267 set peer netnsid for a cross-netns interface
1268
1269 .TP
1270 .BI type " ETYPE TYPE_ARGS"
1271 Change type-specific settings. For a list of supported types and arguments refer
1272 to the description of
1273 .B "ip link add"
1274 above. In addition to that, it is possible to manipulate settings to slave
1275 devices:
1276
1277 .TP
1278 Bridge Slave Support
1279 For a link with master
1280 .B bridge
1281 the following additional arguments are supported:
1282
1283 .B "ip link set type bridge_slave"
1284 [
1285 .BI state " STATE"
1286 ] [
1287 .BI priority " PRIO"
1288 ] [
1289 .BI cost " COST"
1290 ] [
1291 .BR guard " { " on " | " off " }"
1292 ] [
1293 .BR hairpin " { " on " | " off " }"
1294 ] [
1295 .BR fastleave " { " on " | " off " }"
1296 ] [
1297 .BR root_block " { " on " | " off " }"
1298 ] [
1299 .BR learning " { " on " | " off " }"
1300 ] [
1301 .BR flood " { " on " | " off " }"
1302 ] [
1303 .BR proxy_arp " { " on " | " off " }"
1304 ] [
1305 .BR proxy_arp_wifi " { " on " | " off " }"
1306 ] [
1307 .BI mcast_router " MULTICAST_ROUTER"
1308 ] [
1309 .BR mcast_fast_leave " { " on " | " off "} ]"
1310
1311 .in +8
1312 .sp
1313 .BI state " STATE"
1314 - Set port state.
1315 .I STATE
1316 is a number representing the following states:
1317 .BR 0 " (disabled),"
1318 .BR 1 " (listening),"
1319 .BR 2 " (learning),"
1320 .BR 3 " (forwarding),"
1321 .BR 4 " (blocking)."
1322
1323 .BI priority " PRIO"
1324 - set port priority (a 16bit unsigned value).
1325
1326 .BI cost " COST"
1327 - set port cost (a 32bit unsigned value).
1328
1329 .BR guard " { " on " | " off " }"
1330 - block incoming BPDU packets on this port.
1331
1332 .BR hairpin " { " on " | " off " }"
1333 - enable hairpin mode on this port. This will allow incoming packets on this
1334 port to be reflected back.
1335
1336 .BR fastleave " { " on " | " off " }"
1337 - enable multicast fast leave on this port.
1338
1339 .BR root_block " { " on " | " off " }"
1340 - block this port from becoming the bridge's root port.
1341
1342 .BR learning " { " on " | " off " }"
1343 - allow MAC address learning on this port.
1344
1345 .BR flood " { " on " | " off " }"
1346 - open the flood gates on this port, i.e. forward all unicast frames to this
1347 port also. Requires
1348 .BR proxy_arp " and " proxy_arp_wifi
1349 to be turned off.
1350
1351 .BR proxy_arp " { " on " | " off " }"
1352 - enable proxy ARP on this port.
1353
1354 .BR proxy_arp_wifi " { " on " | " off " }"
1355 - enable proxy ARP on this port which meets extended requirements by IEEE
1356 802.11 and Hotspot 2.0 specifications.
1357
1358 .BI mcast_router " MULTICAST_ROUTER"
1359 - configure this port for having multicast routers attached. A port with a
1360 multicast router will receive all multicast traffic.
1361 .I MULTICAST_ROUTER
1362 may be either
1363 .B 0
1364 to disable multicast routers on this port,
1365 .B 1
1366 to let the system detect the presence of of routers (this is the default),
1367 .B 2
1368 to permanently enable multicast traffic forwarding on this port or
1369 .B 3
1370 to enable multicast routers temporarily on this port, not depending on incoming
1371 queries.
1372
1373 .BR mcast_fast_leave " { " on " | " off " }"
1374 - this is a synonym to the
1375 .B fastleave
1376 option above.
1377
1378 .in -8
1379
1380 .TP
1381 Bonding Slave Support
1382 For a link with master
1383 .B bond
1384 the following additional arguments are supported:
1385
1386 .B "ip link set type bond_slave"
1387 [
1388 .BI queue_id " ID"
1389 ]
1390
1391 .in +8
1392 .sp
1393 .BI queue_id " ID"
1394 - set the slave's queue ID (a 16bit unsigned value).
1395
1396 .in -8
1397
1398 .SS  ip link show - display device attributes
1399
1400 .TP
1401 .BI dev " NAME " (default)
1402 .I NAME
1403 specifies the network device to show.
1404 If this argument is omitted all devices in the default group are listed.
1405
1406 .TP
1407 .BI group " GROUP "
1408 .I GROUP
1409 specifies what group of devices to show.
1410
1411 .TP
1412 .B up
1413 only display running interfaces.
1414
1415 .TP
1416 .BI master " DEVICE "
1417 .I DEVICE
1418 specifies the master device which enslaves devices to show.
1419
1420 .TP
1421 .BI vrf " NAME "
1422 .I NAME
1423 speficies the VRF which enslaves devices to show.
1424
1425 .TP
1426 .BI type " TYPE "
1427 .I TYPE
1428 specifies the type of devices to show.
1429
1430 Note that the type name is not checked against the list of supported types -
1431 instead it is sent as-is to the kernel. Later it is used to filter the returned
1432 interface list by comparing it with the relevant attribute in case the kernel
1433 didn't filter already. Therefore any string is accepted, but may lead to empty
1434 output.
1435
1436 .SS  ip link help - display help
1437
1438 .PP
1439 .I "TYPE"
1440 specifies which help of link type to dislpay.
1441
1442 .SS
1443 .I GROUP
1444 may be a number or a string from the file
1445 .B @SYSCONFDIR@/group
1446 which can be manually filled.
1447
1448 .SH "EXAMPLES"
1449 .PP
1450 ip link show
1451 .RS 4
1452 Shows the state of all network interfaces on the system.
1453 .RE
1454 .PP
1455 ip link show type bridge
1456 .RS 4
1457 Shows the bridge devices.
1458 .RE
1459 .PP
1460 ip link show type vlan
1461 .RS 4
1462 Shows the vlan devices.
1463 .RE
1464 .PP
1465 ip link show master br0
1466 .RS 4
1467 Shows devices enslaved by br0
1468 .RE
1469 .PP
1470 ip link set dev ppp0 mtu 1400
1471 .RS 4
1472 Change the MTU the ppp0 device.
1473 .RE
1474 .PP
1475 ip link add link eth0 name eth0.10 type vlan id 10
1476 .RS 4
1477 Creates a new vlan device eth0.10 on device eth0.
1478 .RE
1479 .PP
1480 ip link delete dev eth0.10
1481 .RS 4
1482 Removes vlan device.
1483 .RE
1484
1485 ip link help gre
1486 .RS 4
1487 Display help for the gre link type.
1488 .RE
1489 .PP
1490 ip link add name tun1 type ipip remote 192.168.1.1
1491 local 192.168.1.2 ttl 225 encap gue encap-sport auto
1492 encap-dport 5555 encap-csum encap-remcsum
1493 .RS 4
1494 Creates an IPIP that is encapsulated with Generic UDP Encapsulation,
1495 and the outer UDP checksum and remote checksum offload are enabled.
1496
1497 .RE
1498 .PP
1499 ip link add link wpan0 lowpan0 type lowpan
1500 .RS 4
1501 Creates a 6LoWPAN interface named lowpan0 on the underlying
1502 IEEE 802.15.4 device wpan0.
1503 .RE
1504
1505 .SH SEE ALSO
1506 .br
1507 .BR ip (8),
1508 .BR ip-netns (8),
1509 .BR ethtool (8),
1510 .BR iptables (8)
1511
1512 .SH AUTHOR
1513 Original Manpage by Michail Litvak <mci@owl.openwall.com>