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
  10 .RI "[ " OPTIONS " ]"
  11 .B link
  12 .RI  " { " COMMAND " | "
  13 .BR help " }"
  14 .sp
  15
  16 .ti -8
  17 .IR OPTIONS " := { "
  18 \fB\-V\fR[\fIersion\fR] |
  19 \fB\-h\fR[\fIuman-readable\fR] |
  20 \fB\-s\fR[\fItatistics\fR] |
  21 \fB\-r\fR[\fIesolve\fR] |
  22 \fB\-f\fR[\fIamily\fR] {
  23 .BR inet " | " inet6 " | " ipx " | " dnet " | " link " } | "
  24 \fB\-o\fR[\fIneline\fR] }
  25
  26 .ti -8
  27 .BI "ip link add"
  28 .RB "[ " link
  29 .IR DEVICE " ]"
  30 .RB "[ " name " ]"
  31 .I NAME
  32 .br
  33 .RB "[ " txqueuelen
  34 .IR PACKETS " ]"
  35 .br
  36 .RB "[ " address
  37 .IR LLADDR " ]"
  38 .RB "[ " broadcast
  39 .IR LLADDR " ]"
  40 .br
  41 .RB "[ " mtu
  42 .IR MTU " ]"
  43 .RB "[ " index
  44 .IR IDX " ]"
  45 .br
  46 .RB "[ " numtxqueues
  47 .IR QUEUE_COUNT " ]"
  48 .RB "[ " numrxqueues
  49 .IR QUEUE_COUNT " ]"
  50 .br
  51 .BR type " TYPE"
  52 .RI "[ " ARGS " ]"
  53
  54 .ti -8
  55 .IR TYPE " := [ "
  56 .BR bridge " | "
  57 .BR bond " | "
  58 .BR can " | "
  59 .BR dummy " | "
  60 .BR hsr " | "
  61 .BR ifb " | "
  62 .BR ipoib " |"
  63 .BR macvlan  " | "
  64 .BR macvtap  " | "
  65 .BR vcan " | "
  66 .BR veth " | "
  67 .BR vlan " | "
  68 .BR vxlan " |"
  69 .BR ip6tnl " |"
  70 .BR ipip " |"
  71 .BR sit " |"
  72 .BR gre " |"
  73 .BR gretap " |"
  74 .BR ip6gre " |"
  75 .BR ip6gretap " ]"
  76
  77 .ti -8
  78 .BI "ip link delete " DEVICE
  79 .BI type " TYPE"
  80 .RI "[ " ARGS " ]"
  81
  82 .ti -8
  83 .BR "ip link set " {
  84 .IR DEVICE " | "
  85 .BI "group " GROUP
  86 .RB "} { " up " | " down " | " arp " { " on " | " off " } |"
  87 .br
  88 .BR promisc " { " on " | " off " } |"
  89 .br
  90 .BR allmulticast " { " on " | " off " } |"
  91 .br
  92 .BR dynamic " { " on " | " off " } |"
  93 .br
  94 .BR multicast " { " on " | " off " } |"
  95 .br
  96 .B  txqueuelen
  97 .IR PACKETS " |"
  98 .br
  99 .B  name
 100 .IR NEWNAME " |"
 101 .br
 102 .B  address
 103 .IR LLADDR " |"
 104 .B  broadcast
 105 .IR LLADDR " |"
 106 .br
 107 .B  mtu
 108 .IR MTU " |"
 109 .br
 110 .B  netns
 111 .IR PID " |"
 112 .br
 113 .B  netns
 114 .IR NETNSNAME " |"
 115 .br
 116 .B alias
 117 .IR NAME  " |"
 118 .br
 119 .B vf
 120 .IR NUM " ["
 121 .B  mac
 122 .IR LLADDR " ] ["
 123 .B vlan
 124 .IR VLANID " [ "
 125 .B qos
 126 .IR VLAN-QOS " ] ] ["
 127 .B rate
 128 .IR TXRATE " ] ["
 129 .B max_tx_rate
 130 .IR TXRATE " ] ["
 131 .B min_tx_rate
 132 .IR TXRATE " ] ["
 133 .B spoofchk { on | off } ] [
 134 .B state { auto | enable | disable}
 135 ] |
 136 .br
 137 .B master
 138 .IR DEVICE
 139 .br
 140 .B nomaster
 141 .BR " }"
 142
 143
 144 .ti -8
 145 .B ip link show
 146 .RI "[ " DEVICE " | "
 147 .B group
 148 .IR GROUP " | "
 149 .BR up " | "
 150 .B master
 151 .IR DEVICE " | "
 152 .B type
 153 .IR TYPE " ]"
 154
 155 .ti -8
 156 .B ip link help
 157 .RI "[ " TYPE " ]"
 158
 159 .SH "DESCRIPTION"
 160 .SS ip link add - add virtual link
 161
 162 .TP
 163 .BI link " DEVICE "
 164 specifies the physical device to act operate on.
 165
 166 .I NAME
 167 specifies the name of the new virtual device.
 168
 169 .I TYPE
 170 specifies the type of the new device.
 171 .sp
 172 Link types:
 173
 174 .in +8
 175 .B bridge
 176 - Ethernet Bridge device
 177 .sp
 178 .B bond
 179 - Bonding device
 180 .sp
 181 .B dummy
 182 - Dummy network interface
 183 .sp
 184 .B hsr
 185 - High-availability Seamless Redundancy device
 186 .sp
 187 .B ifb
 188 - Intermediate Functional Block device
 189 .sp
 190 .B ipoib
 191 - IP over Infiniband device
 192 .sp
 193 .B macvlan
 194 - Virtual interface base on link layer address (MAC)
 195 .sp
 196 .B macvtap
 197 - Virtual interface based on link layer address (MAC) and TAP.
 198 .sp
 199 .B vcan
 200 - Virtual Controller Area Network interface
 201 .sp
 202 .B veth
 203 - Virtual ethernet interface
 204 .sp
 205 .BR vlan
 206 - 802.1q tagged virtual LAN interface
 207 .sp
 208 .BR vxlan
 209 - Virtual eXtended LAN
 210 .sp
 211 .BR ip6tnl
 212 - Virtual tunnel interface IPv4|IPv6 over IPv6
 213 .sp
 214 .BR ipip
 215 - Virtual tunnel interface IPv4 over IPv4
 216 .sp
 217 .BR sit
 218 - Virtual tunnel interface IPv6 over IPv4
 219 .sp
 220 .BR gre
 221 - Virtual tunnel interface GRE over IPv4
 222 .sp
 223 .BR gretap
 224 - Virtual L2 tuunel interface GRE over IPv4
 225 .sp
 226 .BR ip6gre
 227 - Virtual tuunel interface GRE over IPv6
 228 .sp
 229 .BR ip6gretap
 230 - Virtual L2 tuunel interface GRE over IPv6
 231 .in -8
 232
 233 .TP
 234 .BI numtxqueues " QUEUE_COUNT "
 235 specifies the number of transmit queues for new device.
 236
 237 .TP
 238 .BI numrxqueues " QUEUE_COUNT "
 239 specifies the number of receive queues for new device.
 240
 241 .TP
 242 .BI index " IDX "
 243 specifies the desired index of the new virtual device. The link creation fails, if the index is busy.
 244
 245 .TP
 246 VXLAN Type Support
 247 For a link of type
 248 .I VXLAN
 249 the following additional arguments are supported:
 250
 251 .BI "ip link add " DEVICE
 252 .BI type " vxlan " id " ID"
 253 .R " [ "
 254 .BI dev " PHYS_DEV "
 255 .RB " ] [ { " group " | " remote " } "
 256 .I IPADDR
 257 .R " ] [ "
 258 .BI local " IPADDR "
 259 .R " ] [ "
 260 .BI ttl " TTL "
 261 .R " ] [ "
 262 .BI tos " TOS "
 263 .R " ] [ "
 264 .BI port " MIN MAX "
 265 .R " ] [ "
 266 .I "[no]learning "
 267 .R " ] [ "
 268 .I "[no]proxy "
 269 .R " ] [ "
 270 .I "[no]rsc "
 271 .R " ] [ "
 272 .I "[no]l2miss "
 273 .R " ] [ "
 274 .I "[no]l3miss "
 275 .R " ] [ "
 276 .BI ageing " SECONDS "
 277 .R " ] [ "
 278 .BI maxaddress " NUMBER "
 279 .R " ]"
 280
 281 .in +8
 282 .sp
 283 .BI  id " VNI "
 284 - specifies the VXLAN Network Identifer (or VXLAN Segment
 285 Identifier) to use.
 286
 287 .BI dev " PHYS_DEV"
 288 - specifies the physical device to use for tunnel endpoint communication.
 289
 290 .sp
 291 .BI group " IPADDR"
 292 - specifies the multicast IP address to join.
 293 This parameter cannot be specified with the
 294 .B remote
 295 parameter.
 296
 297 .sp
 298 .BI remote " IPADDR"
 299 - specifies the unicast destination IP address to use in outgoing packets
 300 when the destination link layer address is not known in the VXLAN device
 301 forwarding database.  This parameter cannot be specified with the
 302 .B group
 303 parameter.
 304
 305 .sp
 306 .BI local " IPADDR"
 307 - specifies the source IP address to use in outgoing packets.
 308
 309 .sp
 310 .BI ttl " TTL"
 311 - specifies the TTL value to use in outgoing packets.
 312
 313 .sp
 314 .BI tos " TOS"
 315 - specifies the TOS value to use in outgoing packets.
 316
 317 .sp
 318 .BI port " MIN MAX"
 319 - specifies the range of port numbers to use as UDP
 320 source ports to communicate to the remote VXLAN tunnel endpoint.
 321
 322 .sp
 323 .I [no]learning
 324 - specifies if unknown source link layer addresses and IP addresses
 325 are entered into the VXLAN device forwarding database.
 326
 327 .sp
 328 .I [no]rsc
 329 - specifies if route short circuit is turned on.
 330
 331 .sp
 332 .I [no]proxy
 333 - specifies ARP proxy is turned on.
 334
 335 .sp
 336 .I [no]l2miss
 337 - specifies if netlink LLADDR miss notifications are generated.
 338
 339 .sp
 340 .I [no]l3miss
 341 - specifies if netlink IP ADDR miss notifications are generated.
 342
 343 .sp
 344 .BI ageing " SECONDS"
 345 - specifies the lifetime in seconds of FDB entries learnt by the kernel.
 346
 347 .sp
 348 .BI maxaddress " NUMBER"
 349 - specifies the maximum number of FDB entries.
 350
 351 .in -8
 352
 353 .TP
 354 IP6GRE/IP6GRETAP Type Support
 355 For a link of type
 356 .I IP6GRE/IP6GRETAP
 357 the following additional arguments are supported:
 358
 359 .BI "ip link add " DEVICE
 360 .BI type " { ip6gre | ip6gretap }  " remote " ADDR " local " ADDR
 361 .R " [ "
 362 .I "[i|o]seq]"
 363 .R " ] [ "
 364 .I "[i|o]key" KEY
 365 .R " ] [ "
 366 .I " [i|o]csum "
 367 .R " ] [ "
 368 .BI hoplimit " TTL "
 369 .R " ] [ "
 370 .BI encaplimit " ELIM "
 371 .R " ] [ "
 372 .BI tclass " TCLASS "
 373 .R " ] [ "
 374 .BI flowlabel " FLOWLABEL "
 375 .R " ] [ "
 376 .BI "dscp inherit"
 377 .R " ] [ "
 378 .BI dev " PHYS_DEV "
 379 .R " ]"
 380
 381 .in +8
 382 .sp
 383 .BI  remote " ADDR "
 384 - specifies the remote IPv6 address of the tunnel.
 385
 386 .sp
 387 .BI  local " ADDR "
 388 - specifies the fixed local IPv6 address for tunneled packets.
 389 It must be and address on another interface on this host.
 390
 391 .sp
 392 .BI  [i|o]seq
 393 - serialize packets.
 394 The
 395 .B oseq
 396 flag enables sequencing of outgoing packets.
 397 The
 398 .B iseq
 399 flag requires that all input packets are serialized.
 400
 401 .sp
 402 .BI  [i|o]key " KEY"
 403 - use keyed GRE with key
 404 .IR KEY ". "KEY
 405 is either a number or an IPv4 address-like dotted quad.
 406 The
 407 .B key
 408 parameter specifies the same key to use in both directions.
 409 The
 410 .BR ikey " and " okey
 411 parameters specify different keys for input and output.
 412
 413 .sp
 414 .BI  [i|o]csum
 415 - generate/require checksums for tunneled packets.
 416 The
 417 .B ocsum
 418 flag calculates checksums for outgoing packets.
 419 The
 420 .B icsum
 421 flag requires that all input packets have the correct
 422 checksum.  The
 423 .B csum
 424 flag is equivalent to the combination
 425 .BR "icsum ocsum" .
 426
 427 .sp
 428 .BI  hoplimit " TTL"
 429 - specifies Hop Limit value to use in outgoing packets.
 430
 431 .sp
 432 .BI  encaplimit " ELIM"
 433 - specifies a fixed encapsulation limit.  Default is 4.
 434
 435 .sp
 436 .BI  flowlabel " FLOWLABEL"
 437 - specifies a fixed flowlabel.
 438
 439 .sp
 440 .BI  tclass " TCLASS"
 441 - specifies the traffic class field on
 442 tunneled packets, which can be specified as either a two-digit
 443 hex value (e.g. c0) or a predefined string (e.g. internet).
 444 The value
 445 .B inherit
 446 causes the field to be copied from the original IP header. The
 447 values
 448 .BI "inherit/" STRING
 449 or
 450 .BI "inherit/" 00 ".." ff
 451 will set the field to
 452 .I STRING
 453 or
 454 .IR 00 ".." ff
 455 when tunneling non-IP packets. The default value is 00.
 456
 457 .in -8
 458
 459 .TP
 460 IPoIB Type Support
 461 For a link of type
 462 .I IPoIB
 463 the following additional arguments are supported:
 464
 465 .BI "ip link add " DEVICE " name " NAME
 466 .BI type " ipoib [ " pkey " PKEY ] [" mode " MODE " ]
 467
 468 .in +8
 469 .sp
 470 .BI  pkey " PKEY "
 471 - specifies the IB P-Key to use.
 472
 473 .BI  mode " MODE "
 474 - specifies the mode (datagram or connected) to use.
 475
 476 .SS ip link delete - delete virtual link
 477 .I DEVICE
 478 specifies the virtual  device to act operate on.
 479 .I TYPE
 480 specifies the type of the device.
 481
 482
 483 .TP
 484 .BI dev " DEVICE "
 485 specifies the physical device to act operate on.
 486
 487 .SS ip link set - change device attributes
 488
 489 .TP
 490 .BI dev " DEVICE "
 491 .I DEVICE
 492 specifies network device to operate on. When configuring SR-IOV Virtual Function
 493 (VF) devices, this keyword should specify the associated Physical Function (PF)
 494 device.
 495
 496 .TP
 497 .BI group " GROUP "
 498 .I GROUP
 499 has a dual role: If both group and dev are present, then move the device to the
 500 specified group.  If only a group is specified, then the command operates on
 501 all devices in that group.
 502
 503 .TP
 504 .BR up " and " down
 505 change the state of the device to
 506 .B UP
 507 or
 508 .BR "DOWN" .
 509
 510 .TP
 511 .BR "arp on " or " arp off"
 512 change the
 513 .B NOARP
 514 flag on the device.
 515
 516 .TP
 517 .BR "multicast on " or " multicast off"
 518 change the
 519 .B MULTICAST
 520 flag on the device.
 521
 522 .TP
 523 .BR "dynamic on " or " dynamic off"
 524 change the
 525 .B DYNAMIC
 526 flag on the device.
 527
 528 .TP
 529 .BI name " NAME"
 530 change the name of the device.  This operation is not
 531 recommended if the device is running or has some addresses
 532 already configured.
 533
 534 .TP
 535 .BI txqueuelen " NUMBER"
 536 .TP
 537 .BI txqlen " NUMBER"
 538 change the transmit queue length of the device.
 539
 540 .TP
 541 .BI mtu " NUMBER"
 542 change the
 543 .I MTU
 544 of the device.
 545
 546 .TP
 547 .BI address " LLADDRESS"
 548 change the station address of the interface.
 549
 550 .TP
 551 .BI broadcast " LLADDRESS"
 552 .TP
 553 .BI brd " LLADDRESS"
 554 .TP
 555 .BI peer " LLADDRESS"
 556 change the link layer broadcast address or the peer address when
 557 the interface is
 558 .IR "POINTOPOINT" .
 559
 560 .TP
 561 .BI netns " PID"
 562 move the device to the network namespace associated with the process
 563 .IR "PID".
 564
 565 .TP
 566 .BI netns " NETNSNAME"
 567 move the device to the network namespace associated with name
 568 .IR "NETNSNAME".
 569
 570 .TP
 571 .BI alias " NAME"
 572 give the device a symbolic name for easy reference.
 573
 574 .TP
 575 .BI group " GROUP"
 576 specify the group the device belongs to.
 577 The available groups are listed in file
 578 .BR "@SYSCONFDIR@/group" .
 579
 580 .TP
 581 .BI vf " NUM"
 582 specify a Virtual Function device to be configured. The associated PF device
 583 must be specified using the
 584 .B dev
 585 parameter.
 586
 587 .in +8
 588 .BI mac " LLADDRESS"
 589 - change the station address for the specified VF. The
 590 .B vf
 591 parameter must be specified.
 592
 593 .sp
 594 .BI vlan " VLANID"
 595 - change the assigned VLAN for the specified VF. When specified, all traffic
 596 sent from the VF will be tagged with the specified VLAN ID. Incoming traffic
 597 will be filtered for the specified VLAN ID, and will have all VLAN tags
 598 stripped before being passed to the VF. Setting this parameter to 0 disables
 599 VLAN tagging and filtering. The
 600 .B vf
 601 parameter must be specified.
 602
 603 .sp
 604 .BI qos " VLAN-QOS"
 605 - assign VLAN QOS (priority) bits for the VLAN tag. When specified, all VLAN
 606 tags transmitted by the VF will include the specified priority bits in the
 607 VLAN tag. If not specified, the value is assumed to be 0. Both the
 608 .B vf
 609 and
 610 .B vlan
 611 parameters must be specified. Setting both
 612 .B vlan
 613 and
 614 .B qos
 615 as 0 disables VLAN tagging and filtering for the VF.
 616
 617 .sp
 618 .BI rate " TXRATE"
 619 -- change the allowed transmit bandwidth, in Mbps, for the specified VF.
 620 Setting this parameter to 0 disables rate limiting.
 621 .B vf
 622 parameter must be specified.
 623 Please use new API
 624 .B "max_tx_rate"
 625 option instead.
 626
 627 .sp
 628 .BI max_tx_rate " TXRATE"
 629 - change the allowed maximum transmit bandwidth, in Mbps, for the specified VF.
 630 .B vf
 631 parameter must be specified.
 632
 633 .sp
 634 .BI min_tx_rate " TXRATE"
 635 - change the allowed minimum transmit bandwidth, in Mbps, for the specified VF.
 636 Minimum TXRATE should be always <= Maximum TXRATE.
 637 .B vf
 638 parameter must be specified.
 639
 640 .sp
 641 .BI spoofchk " on|off"
 642 - turn packet spoof checking on or off for the specified VF.
 643 .sp
 644 .BI state " auto|enable|disable"
 645 - set the virtual link state as seen by the specified VF. Setting to auto means a
 646 reflection of the PF link state, enable lets the VF to communicate with other VFs on
 647 this host even if the PF link state is down, disable causes the HW to drop any packets
 648 sent by the VF.
 649 .in -8
 650
 651 .TP
 652 .BI master " DEVICE"
 653 set master device of the device (enslave device).
 654
 655 .TP
 656 .BI nomaster
 657 unset master device of the device (release device).
 658
 659 .PP
 660 .B Warning:
 661 If multiple parameter changes are requested,
 662 .B ip
 663 aborts immediately after any of the changes have failed.
 664 This is the only case when
 665 .B ip
 666 can move the system to an unpredictable state.  The solution
 667 is to avoid changing several parameters with one
 668 .B ip link set
 669 call.
 670
 671 .SS  ip link show - display device attributes
 672
 673 .TP
 674 .BI dev " NAME " (default)
 675 .I NAME
 676 specifies the network device to show.
 677 If this argument is omitted all devices in the default group are listed.
 678
 679 .TP
 680 .BI group " GROUP "
 681 .I GROUP
 682 specifies what group of devices to show.
 683
 684 .TP
 685 .B up
 686 only display running interfaces.
 687
 688 .TP
 689 .BI master " DEVICE "
 690 .I DEVICE
 691 specifies the master device which enslaves devices to show.
 692
 693 .TP
 694 .BI type " TYPE "
 695 .I TYPE
 696 specifies the type of devices to show.
 697
 698 .TP
 699 The show command has additional formatting options:
 700
 701 .RS
 702 .TP
 703 .BR "\-s" , " \-stats", " \-statistics"
 704 output more statistics about packet usage.
 705
 706 .TP
 707 .BR "\-d", " \-details"
 708 output more detailed information.
 709
 710 .TP
 711 .BR "\-h", " \-human", " \-human-readble"
 712 output statistics with human readable values number followed by suffix
 713
 714 .TP
 715 .BR "\-iec"
 716 print human readable rates in IEC units (ie. 1K = 1024).
 717 .RE
 718
 719 .SS  ip link help - display help
 720
 721 .PP
 722 .I "TYPE"
 723 specifies which help of link type to dislpay.
 724
 725 .SH "EXAMPLES"
 726 .PP
 727 ip link show
 728 .RS 4
 729 Shows the state of all network interfaces on the system.
 730 .RE
 731 .PP
 732 ip link show type bridge
 733 .RS 4
 734 Shows the bridge devices.
 735 .RE
 736 .PP
 737 ip link show type vlan
 738 .RS 4
 739 Shows the vlan devices.
 740 .RE
 741 .PP
 742 ip link set dev ppp0 mtu 1400
 743 .RS 4
 744 Change the MTU the ppp0 device.
 745 .RE
 746 .PP
 747 ip link add link eth0 name eth0.10 type vlan id 10
 748 .RS 4
 749 Creates a new vlan device eth0.10 on device eth0.
 750 .RE
 751 .PP
 752 ip link delete dev eth0.10
 753 .RS 4
 754 Removes vlan device.
 755 .RE
 756
 757 ip link help gre
 758 .RS 4
 759 Display help for the gre link type.
 760 .RE
 761
 762 .SH SEE ALSO
 763 .br
 764 .BR ip (8)
 765
 766 .SH AUTHOR
 767 Original Manpage by Michail Litvak <mci@owl.openwall.com>