man/man8/ip-route.8

   1 .TH IP\-ROUTE 8 "20 Dec 2011" "iproute2" "Linux"
   2 .SH "NAME"
   3 ip-route \- routing table management
   4 .SH "SYNOPSIS"
   5 .sp
   6 .ad l
   7 .in +8
   8 .ti -8
   9 .B ip
  10 .RI "[ " OPTIONS " ]"
  11 .B route
  12 .RI " { " COMMAND " | "
  13 .BR help " }"
  14 .sp
  15 .ti -8
  16
  17 .ti -8
  18 .BR "ip route" " { "
  19 .BR list " | " flush " } "
  20 .I  SELECTOR
  21
  22 .ti -8
  23 .BR "ip route save"
  24 .I SELECTOR
  25
  26 .ti -8
  27 .BR "ip route restore"
  28
  29 .ti -8
  30 .B  ip route get
  31 .IR ADDRESS " [ "
  32 .BI from " ADDRESS " iif " STRING"
  33 .RB " ] [ " oif
  34 .IR STRING " ] [ "
  35 .B  tos
  36 .IR TOS " ]"
  37
  38 .ti -8
  39 .BR "ip route" " { " add " | " del " | " change " | " append " | "\
  40 replace " } "
  41 .I  ROUTE
  42
  43 .ti -8
  44 .IR SELECTOR " := "
  45 .RB "[ " root
  46 .IR PREFIX " ] [ "
  47 .B  match
  48 .IR PREFIX " ] [ "
  49 .B  exact
  50 .IR PREFIX " ] [ "
  51 .B  table
  52 .IR TABLE_ID " ] [ "
  53 .B  proto
  54 .IR RTPROTO " ] [ "
  55 .B  type
  56 .IR TYPE " ] [ "
  57 .B  scope
  58 .IR SCOPE " ]"
  59
  60 .ti -8
  61 .IR ROUTE " := " NODE_SPEC " [ " INFO_SPEC " ]"
  62
  63 .ti -8
  64 .IR NODE_SPEC " := [ " TYPE " ] " PREFIX " ["
  65 .B  tos
  66 .IR TOS " ] [ "
  67 .B  table
  68 .IR TABLE_ID " ] [ "
  69 .B  proto
  70 .IR RTPROTO " ] [ "
  71 .B  scope
  72 .IR SCOPE " ] [ "
  73 .B  metric
  74 .IR METRIC " ]"
  75
  76 .ti -8
  77 .IR INFO_SPEC " := " "NH OPTIONS FLAGS" " ["
  78 .B  nexthop
  79 .IR NH " ] ..."
  80
  81 .ti -8
  82 .IR NH " := [ "
  83 .B  via
  84 .IR ADDRESS " ] [ "
  85 .B  dev
  86 .IR STRING " ] [ "
  87 .B  weight
  88 .IR NUMBER " ] " NHFLAGS
  89
  90 .ti -8
  91 .IR OPTIONS " := " FLAGS " [ "
  92 .B  mtu
  93 .IR NUMBER " ] [ "
  94 .B  advmss
  95 .IR NUMBER " ] [ "
  96 .B  rtt
  97 .IR TIME " ] [ "
  98 .B  rttvar
  99 .IR TIME " ] [ "
 100 .B  window
 101 .IR NUMBER " ] [ "
 102 .B  cwnd
 103 .IR NUMBER " ] [ "
 104 .B  ssthresh
 105 .IR REALM " ] [ "
 106 .B  realms
 107 .IR REALM " ] [ "
 108 .B  rto_min
 109 .IR TIME " ] [ "
 110 .B  initcwnd
 111 .IR NUMBER " ] [ "
 112 .B  initrwnd
 113 .IR NUMBER " ]"
 114
 115 .ti -8
 116 .IR TYPE " := [ "
 117 .BR unicast " | " local " | " broadcast " | " multicast " | "\
 118 throw " | " unreachable " | " prohibit " | " blackhole " | " nat " ]"
 119
 120 .ti -8
 121 .IR TABLE_ID " := [ "
 122 .BR local "| " main " | " default " | " all " |"
 123 .IR NUMBER " ]"
 124
 125 .ti -8
 126 .IR SCOPE " := [ "
 127 .BR host " | " link " | " global " |"
 128 .IR NUMBER " ]"
 129
 130 .ti -8
 131 .IR NHFLAGS " := [ "
 132 .BR onlink " | " pervasive " ]"
 133
 134 .ti -8
 135 .IR RTPROTO " := [ "
 136 .BR kernel " | " boot " | " static " |"
 137 .IR NUMBER " ]"
 138
 139
 140 .SH DESCRIPTION
 141 .B ip route
 142 is used to manipulate entries in the kernel routing tables.
 143 .sp
 144 .B Route types:
 145
 146 .in +8
 147 .B unicast
 148 - the route entry describes real paths to the destinations covered
 149 by the route prefix.
 150
 151 .sp
 152 .B unreachable
 153 - these destinations are unreachable.  Packets are discarded and the
 154 ICMP message
 155 .I host unreachable
 156 is generated.
 157 The local senders get an
 158 .I EHOSTUNREACH
 159 error.
 160
 161 .sp
 162 .B blackhole
 163 - these destinations are unreachable.  Packets are discarded silently.
 164 The local senders get an
 165 .I EINVAL
 166 error.
 167
 168 .sp
 169 .B prohibit
 170 - these destinations are unreachable.  Packets are discarded and the
 171 ICMP message
 172 .I communication administratively prohibited
 173 is generated.  The local senders get an
 174 .I EACCES
 175 error.
 176
 177 .sp
 178 .B local
 179 - the destinations are assigned to this host.  The packets are looped
 180 back and delivered locally.
 181
 182 .sp
 183 .B broadcast
 184 - the destinations are broadcast addresses.  The packets are sent as
 185 link broadcasts.
 186
 187 .sp
 188 .B throw
 189 - a special control route used together with policy rules. If such a
 190 route is selected, lookup in this table is terminated pretending that
 191 no route was found.  Without policy routing it is equivalent to the
 192 absence of the route in the routing table.  The packets are dropped
 193 and the ICMP message
 194 .I net unreachable
 195 is generated.  The local senders get an
 196 .I ENETUNREACH
 197 error.
 198
 199 .sp
 200 .B nat
 201 - a special NAT route.  Destinations covered by the prefix
 202 are considered to be dummy (or external) addresses which require translation
 203 to real (or internal) ones before forwarding.  The addresses to translate to
 204 are selected with the attribute
 205 .B Warning:
 206 Route NAT is no longer supported in Linux 2.6.
 207
 208
 209 .BR "via" .
 210 .sp
 211 .B anycast
 212 .RI "- " "not implemented"
 213 the destinations are
 214 .I anycast
 215 addresses assigned to this host.  They are mainly equivalent
 216 to
 217 .B local
 218 with one difference: such addresses are invalid when used
 219 as the source address of any packet.
 220
 221 .sp
 222 .B multicast
 223 - a special type used for multicast routing.  It is not present in
 224 normal routing tables.
 225 .in -8
 226
 227 .P
 228 .B Route tables:
 229 Linux-2.x can pack routes into several routing tables identified
 230 by a number in the range from 1 to 2^31 or by name from the file
 231 .B /etc/iproute2/rt_tables
 232 By default all normal routes are inserted into the
 233 .B main
 234 table (ID 254) and the kernel only uses this table when calculating routes.
 235 Values (0, 253, 254, and 255) are reserved for built-in use.
 236
 237 .sp
 238 Actually, one other table always exists, which is invisible but
 239 even more important.  It is the
 240 .B local
 241 table (ID 255).  This table
 242 consists of routes for local and broadcast addresses.  The kernel maintains
 243 this table automatically and the administrator usually need not modify it
 244 or even look at it.
 245
 246 The multiple routing tables enter the game when
 247 .I policy routing
 248 is used.
 249
 250 .SS ip route add - add new route
 251 .SS ip route change - change route
 252 .SS ip route replace - change or add new one
 253
 254 .TP
 255 .BI to " TYPE PREFIX " (default)
 256 the destination prefix of the route.  If
 257 .I TYPE
 258 is omitted,
 259 .B ip
 260 assumes type
 261 .BR "unicast" .
 262 Other values of
 263 .I TYPE
 264 are listed above.
 265 .I PREFIX
 266 is an IP or IPv6 address optionally followed by a slash and the
 267 prefix length.  If the length of the prefix is missing,
 268 .B ip
 269 assumes a full-length host route.  There is also a special
 270 .I PREFIX
 271 .B default
 272 - which is equivalent to IP
 273 .B 0/0
 274 or to IPv6
 275 .BR "::/0" .
 276
 277 .TP
 278 .BI tos " TOS"
 279 .TP
 280 .BI dsfield " TOS"
 281 the Type Of Service (TOS) key.  This key has no associated mask and
 282 the longest match is understood as: First, compare the TOS
 283 of the route and of the packet.  If they are not equal, then the packet
 284 may still match a route with a zero TOS.
 285 .I TOS
 286 is either an 8 bit hexadecimal number or an identifier
 287 from
 288 .BR "/etc/iproute2/rt_dsfield" .
 289
 290 .TP
 291 .BI metric " NUMBER"
 292 .TP
 293 .BI preference " NUMBER"
 294 the preference value of the route.
 295 .I NUMBER
 296 is an arbitrary 32bit number.
 297
 298 .TP
 299 .BI table " TABLEID"
 300 the table to add this route to.
 301 .I TABLEID
 302 may be a number or a string from the file
 303 .BR "/etc/iproute2/rt_tables" .
 304 If this parameter is omitted,
 305 .B ip
 306 assumes the
 307 .B main
 308 table, with the exception of
 309 .BR local " , " broadcast " and " nat
 310 routes, which are put into the
 311 .B local
 312 table by default.
 313
 314 .TP
 315 .BI dev " NAME"
 316 the output device name.
 317
 318 .TP
 319 .BI via " ADDRESS"
 320 the address of the nexthop router.  Actually, the sense of this field
 321 depends on the route type.  For normal
 322 .B unicast
 323 routes it is either the true next hop router or, if it is a direct
 324 route installed in BSD compatibility mode, it can be a local address
 325 of the interface.  For NAT routes it is the first address of the block
 326 of translated IP destinations.
 327
 328 .TP
 329 .BI src " ADDRESS"
 330 the source address to prefer when sending to the destinations
 331 covered by the route prefix.
 332
 333 .TP
 334 .BI realm " REALMID"
 335 the realm to which this route is assigned.
 336 .I REALMID
 337 may be a number or a string from the file
 338 .BR "/etc/iproute2/rt_realms" .
 339
 340 .TP
 341 .BI mtu " MTU"
 342 .TP
 343 .BI "mtu lock" " MTU"
 344 the MTU along the path to the destination.  If the modifier
 345 .B lock
 346 is not used, the MTU may be updated by the kernel due to
 347 Path MTU Discovery.  If the modifier
 348 .B lock
 349 is used, no path MTU discovery will be tried, all packets
 350 will be sent without the DF bit in IPv4 case or fragmented
 351 to MTU for IPv6.
 352
 353 .TP
 354 .BI window " NUMBER"
 355 the maximal window for TCP to advertise to these destinations,
 356 measured in bytes.  It limits maximal data bursts that our TCP
 357 peers are allowed to send to us.
 358
 359 .TP
 360 .BI rtt " TIME"
 361 the initial RTT ('Round Trip Time') estimate. If no suffix is
 362 specified the units are raw values passed directly to the
 363 routing code to maintain compatibility with previous releases.
 364 Otherwise if a suffix of s, sec or secs is used to specify
 365 seconds and ms, msec or msecs to specify milliseconds.
 366
 367
 368 .TP
 369 .BI rttvar " TIME " "(2.3.15+ only)"
 370 the initial RTT variance estimate. Values are specified as with
 371 .BI rtt
 372 above.
 373
 374 .TP
 375 .BI rto_min " TIME " "(2.6.23+ only)"
 376 the minimum TCP Retransmission TimeOut to use when communicating with this
 377 destination.  Values are specified as with
 378 .BI rtt
 379 above.
 380
 381 .TP
 382 .BI ssthresh " NUMBER " "(2.3.15+ only)"
 383 an estimate for the initial slow start threshold.
 384
 385 .TP
 386 .BI cwnd " NUMBER " "(2.3.15+ only)"
 387 the clamp for congestion window.  It is ignored if the
 388 .B lock
 389 flag is not used.
 390
 391 .TP
 392 .BI initcwnd " NUMBER " "(2.5.70+ only)"
 393 the initial congestion window size for connections to this destination.
 394 Actual window size is this value multiplied by the MSS
 395 (``Maximal Segment Size'') for same connection. The default is
 396 zero, meaning to use the values specified in RFC2414.
 397
 398 .TP
 399 .BI initrwnd " NUMBER " "(2.6.33+ only)"
 400 the initial receive window size for connections to this destination.
 401 Actual window size is this value multiplied by the MSS of the connection.
 402 The default value is zero, meaning to use Slow Start value.
 403
 404 .TP
 405 .BI advmss " NUMBER " "(2.3.15+ only)"
 406 the MSS ('Maximal Segment Size') to advertise to these
 407 destinations when establishing TCP connections.  If it is not given,
 408 Linux uses a default value calculated from the first hop device MTU.
 409 (If the path to these destination is asymmetric, this guess may be wrong.)
 410
 411 .TP
 412 .BI reordering " NUMBER " "(2.3.15+ only)"
 413 Maximal reordering on the path to this destination.
 414 If it is not given, Linux uses the value selected with
 415 .B sysctl
 416 variable
 417 .BR "net/ipv4/tcp_reordering" .
 418
 419 .TP
 420 .BI nexthop " NEXTHOP"
 421 the nexthop of a multipath route.
 422 .I NEXTHOP
 423 is a complex value with its own syntax similar to the top level
 424 argument lists:
 425
 426 .in +8
 427 .BI via " ADDRESS"
 428 - is the nexthop router.
 429 .sp
 430
 431 .BI dev " NAME"
 432 - is the output device.
 433 .sp
 434
 435 .BI weight " NUMBER"
 436 - is a weight for this element of a multipath
 437 route reflecting its relative bandwidth or quality.
 438 .in -8
 439
 440 .TP
 441 .BI scope " SCOPE_VAL"
 442 the scope of the destinations covered by the route prefix.
 443 .I SCOPE_VAL
 444 may be a number or a string from the file
 445 .BR "/etc/iproute2/rt_scopes" .
 446 If this parameter is omitted,
 447 .B ip
 448 assumes scope
 449 .B global
 450 for all gatewayed
 451 .B unicast
 452 routes, scope
 453 .B link
 454 for direct
 455 .BR unicast " and " broadcast
 456 routes and scope
 457 .BR host " for " local
 458 routes.
 459
 460 .TP
 461 .BI protocol " RTPROTO"
 462 the routing protocol identifier of this route.
 463 .I RTPROTO
 464 may be a number or a string from the file
 465 .BR "/etc/iproute2/rt_protos" .
 466 If the routing protocol ID is not given,
 467 .B ip assumes protocol
 468 .B boot
 469 (i.e. it assumes the route was added by someone who doesn't
 470 understand what they are doing).  Several protocol values have
 471 a fixed interpretation.
 472 Namely:
 473
 474 .in +8
 475 .B redirect
 476 - the route was installed due to an ICMP redirect.
 477 .sp
 478
 479 .B kernel
 480 - the route was installed by the kernel during autoconfiguration.
 481 .sp
 482
 483 .B boot
 484 - the route was installed during the bootup sequence.
 485 If a routing daemon starts, it will purge all of them.
 486 .sp
 487
 488 .B static
 489 - the route was installed by the administrator
 490 to override dynamic routing. Routing daemon will respect them
 491 and, probably, even advertise them to its peers.
 492 .sp
 493
 494 .B ra
 495 - the route was installed by Router Discovery protocol.
 496 .in -8
 497
 498 .sp
 499 The rest of the values are not reserved and the administrator is free
 500 to assign (or not to assign) protocol tags.
 501
 502 .TP
 503 .B onlink
 504 pretend that the nexthop is directly attached to this link,
 505 even if it does not match any interface prefix.
 506
 507 .SS ip route delete - delete route
 508
 509 .B ip route del
 510 has the same arguments as
 511 .BR "ip route add" ,
 512 but their semantics are a bit different.
 513
 514 Key values
 515 .RB "(" to ", " tos ", " preference " and " table ")"
 516 select the route to delete.  If optional attributes are present,
 517 .B ip
 518 verifies that they coincide with the attributes of the route to delete.
 519 If no route with the given key and attributes was found,
 520 .B ip route del
 521 fails.
 522
 523 .SS ip route show - list routes
 524 the command displays the contents of the routing tables or the route(s)
 525 selected by some criteria.
 526
 527 .TP
 528 .BI to " SELECTOR " (default)
 529 only select routes from the given range of destinations.
 530 .I SELECTOR
 531 consists of an optional modifier
 532 .RB "(" root ", " match " or " exact ")"
 533 and a prefix.
 534 .BI root " PREFIX"
 535 selects routes with prefixes not shorter than
 536 .IR PREFIX "."
 537 F.e.
 538 .BI root " 0/0"
 539 selects the entire routing table.
 540 .BI match " PREFIX"
 541 selects routes with prefixes not longer than
 542 .IR PREFIX "."
 543 F.e.
 544 .BI match " 10.0/16"
 545 selects
 546 .IR 10.0/16 ","
 547 .IR 10/8 " and " 0/0 ,
 548 but it does not select
 549 .IR 10.1/16 " and " 10.0.0/24 .
 550 And
 551 .BI exact " PREFIX"
 552 (or just
 553 .IR PREFIX ")"
 554 selects routes with this exact prefix. If neither of these options
 555 are present,
 556 .B ip
 557 assumes
 558 .BI root " 0/0"
 559 i.e. it lists the entire table.
 560
 561 .TP
 562 .BI tos " TOS"
 563 .BI dsfield " TOS"
 564 only select routes with the given TOS.
 565
 566 .TP
 567 .BI table " TABLEID"
 568 show the routes from this table(s).  The default setting is to show
 569 .BR table main "."
 570 .I TABLEID
 571 may either be the ID of a real table or one of the special values:
 572 .sp
 573 .in +8
 574 .B all
 575 - list all of the tables.
 576 .sp
 577 .B cache
 578 - dump the routing cache.
 579 .in -8
 580
 581 .TP
 582 .B cloned
 583 .TP
 584 .B cached
 585 list cloned routes i.e. routes which were dynamically forked from
 586 other routes because some route attribute (f.e. MTU) was updated.
 587 Actually, it is equivalent to
 588 .BR "table cache" "."
 589
 590 .TP
 591 .BI from " SELECTOR"
 592 the same syntax as for
 593 .BR to ","
 594 but it binds the source address range rather than destinations.
 595 Note that the
 596 .B from
 597 option only works with cloned routes.
 598
 599 .TP
 600 .BI protocol " RTPROTO"
 601 only list routes of this protocol.
 602
 603 .TP
 604 .BI scope " SCOPE_VAL"
 605 only list routes with this scope.
 606
 607 .TP
 608 .BI type " TYPE"
 609 only list routes of this type.
 610
 611 .TP
 612 .BI dev " NAME"
 613 only list routes going via this device.
 614
 615 .TP
 616 .BI via " PREFIX"
 617 only list routes going via the nexthop routers selected by
 618 .IR PREFIX "."
 619
 620 .TP
 621 .BI src " PREFIX"
 622 only list routes with preferred source addresses selected
 623 by
 624 .IR PREFIX "."
 625
 626 .TP
 627 .BI realm " REALMID"
 628 .TP
 629 .BI realms " FROMREALM/TOREALM"
 630 only list routes with these realms.
 631
 632 .SS ip route flush - flush routing tables
 633 this command flushes routes selected by some criteria.
 634
 635 .sp
 636 The arguments have the same syntax and semantics as the arguments of
 637 .BR "ip route show" ,
 638 but routing tables are not listed but purged.  The only difference is
 639 the default action:
 640 .B show
 641 dumps all the IP main routing table but
 642 .B flush
 643 prints the helper page.
 644
 645 .sp
 646 With the
 647 .B -statistics
 648 option, the command becomes verbose. It prints out the number of
 649 deleted routes and the number of rounds made to flush the routing
 650 table. If the option is given
 651 twice,
 652 .B ip route flush
 653 also dumps all the deleted routes in the format described in the
 654 previous subsection.
 655
 656 .SS ip route get - get a single route
 657 this command gets a single route to a destination and prints its
 658 contents exactly as the kernel sees it.
 659
 660 .TP
 661 .BI to " ADDRESS " (default)
 662 the destination address.
 663
 664 .TP
 665 .BI from " ADDRESS"
 666 the source address.
 667
 668 .TP
 669 .BI tos " TOS"
 670 .TP
 671 .BI dsfield " TOS"
 672 the Type Of Service.
 673
 674 .TP
 675 .BI iif " NAME"
 676 the device from which this packet is expected to arrive.
 677
 678 .TP
 679 .BI oif " NAME"
 680 force the output device on which this packet will be routed.
 681
 682 .TP
 683 .B connected
 684 if no source address
 685 .RB "(option " from ")"
 686 was given, relookup the route with the source set to the preferred
 687 address received from the first lookup.
 688 If policy routing is used, it may be a different route.
 689
 690 .P
 691 Note that this operation is not equivalent to
 692 .BR "ip route show" .
 693 .B show
 694 shows existing routes.
 695 .B get
 696 resolves them and creates new clones if necessary.  Essentially,
 697 .B get
 698 is equivalent to sending a packet along this path.
 699 If the
 700 .B iif
 701 argument is not given, the kernel creates a route
 702 to output packets towards the requested destination.
 703 This is equivalent to pinging the destination
 704 with a subsequent
 705 .BR "ip route ls cache" ,
 706 however, no packets are actually sent.  With the
 707 .B iif
 708 argument, the kernel pretends that a packet arrived from this interface
 709 and searches for a path to forward the packet.
 710
 711 .SS ip route save - save routing table information to stdout
 712 this command behaves like
 713 .BR "ip route show"
 714 except that the output is raw data suitable for passing to
 715 .BR "ip route restore" .
 716
 717 .SS ip route restore - restore routing table information from stdin
 718 this command expects to read a data stream as returned from
 719 .BR "ip route save" .
 720 It will attempt to restore the routing table information exactly as
 721 it was at the time of the save, so any translation of information
 722 in the stream (such as device indexes) must be done first.  Any existing
 723 routes are left unchanged.  Any routes specified in the data stream that
 724 already exist in the table will be ignored.
 725
 726 .SH EXAMPLES
 727 .PP
 728 ip ro
 729 .RS 4
 730 Show all route entries in the kernel.
 731 .RE
 732 .PP
 733 ip route add default via 192.168.1.1 dev eth0
 734 .RS 4
 735 Adds a default route (for all addresses) via the local gateway 192.168.1.1 that can
 736 be reached on device eth0.
 737 .RE
 738
 739 .SH SEE ALSO
 740 .br
 741 .BR ip (8)
 742
 743 .SH AUTHOR
 744 Original Manpage by Michail Litvak <mci@owl.openwall.com>