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