1.\" $Revision: 2.26 $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 4. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)routed.8 8.2 (Berkeley) 12/11/93 31.\" $FreeBSD$ 32.\" 33.Dd June 1, 1996 34.Dt ROUTED 8 35.Os 36.Sh NAME 37.Nm routed , 38.Nm rdisc 39.Nd network RIP and router discovery routing daemon 40.Sh SYNOPSIS 41.Nm 42.Op Fl sqdghmpAtv 43.Op Fl T Ar tracefile 44.Oo 45.Fl F 46.Ar net Ns Op /mask Ns Op ,metric 47.Oc 48.Op Fl P Ar parms 49.Sh DESCRIPTION 50The 51.Nm 52utility is a daemon invoked at boot time to manage the network 53routing tables. 54It uses Routing Information Protocol, RIPv1 (RFC\ 1058), 55RIPv2 (RFC\ 1723), 56and Internet Router Discovery Protocol (RFC 1256) 57to maintain the kernel routing table. 58The RIPv1 protocol is based on the reference 59.Bx 4.3 60daemon. 61.Pp 62It listens on the 63.Xr udp 4 64socket for the 65.Xr route 8 66service (see 67.Xr services 5 ) 68for Routing Information Protocol packets. 69It also sends and receives multicast Router Discovery ICMP messages. 70If the host is a router, 71.Nm 72periodically supplies copies 73of its routing tables to any directly connected hosts and networks. 74It also advertises or solicits default routes using Router Discovery 75ICMP messages. 76.Pp 77When started (or when a network interface is later turned on), 78.Nm 79uses an AF_ROUTE address family facility to find those 80directly connected interfaces configured into the 81system and marked "up". 82It adds necessary routes for the interfaces 83to the kernel routing table. 84Soon after being first started, and provided there is at least one 85interface on which RIP has not been disabled, 86.Nm 87deletes all pre-existing 88non-static routes in kernel table. 89Static routes in the kernel table are preserved and 90included in RIP responses if they have a valid RIP metric 91(see 92.Xr route 8 ) . 93.Pp 94If more than one interface is present (not counting the loopback interface), 95it is assumed that the host should forward packets among the 96connected networks. 97After transmitting a RIP 98.Em request 99and 100Router Discovery Advertisements or Solicitations on a new interface, 101the daemon enters a loop, listening for 102RIP request and response and Router Discovery packets from other hosts. 103.Pp 104When a 105.Em request 106packet is received, 107.Nm 108formulates a reply based on the information maintained in its 109internal tables. 110The 111.Em response 112packet generated contains a list of known routes, each marked 113with a "hop count" metric (a count of 16 or greater is 114considered "infinite"). 115The advertised metric for a route reflects the metrics associated 116with interfaces 117(see 118.Xr ifconfig 8 ) 119though which it is received and sent, 120so setting the metric on an interface 121is an effective way to steer traffic. 122See also 123.Cm adj_inmetric 124and 125.Cm adj_outmetric 126parameters below. 127.Pp 128Responses do not include routes with a first hop on the requesting 129network to implement in part 130.Em split-horizon . 131Requests from query programs 132such as 133.Xr rtquery 8 134are answered with the complete table. 135.Pp 136The routing table maintained by the daemon 137includes space for several gateways for each destination 138to speed recovery from a failing router. 139RIP 140.Em response 141packets received are used to update the routing tables provided they are 142from one of the several currently recognized gateways or 143advertise a better metric than at least one of the existing 144gateways. 145.Pp 146When an update is applied, 147.Nm 148records the change in its own tables and updates the kernel routing table 149if the best route to the destination changes. 150The change in the kernel routing table is reflected in the next batch of 151.Em response 152packets sent. 153If the next response is not scheduled for a while, a 154.Em flash update 155response containing only recently changed routes is sent. 156.Pp 157In addition to processing incoming packets, 158.Nm 159also periodically checks the routing table entries. 160If an entry has not been updated for 3 minutes, the entry's metric 161is set to infinity and marked for deletion. 162Deletions are delayed until the route has been advertised with 163an infinite metric to ensure the invalidation 164is propagated throughout the local internet. 165This is a form of 166.Em poison reverse . 167.Pp 168Routes in the kernel table that are added or changed as a result 169of ICMP Redirect messages are deleted after a while to minimize 170.Em black-holes . 171When a TCP connection suffers a timeout, 172the kernel tells 173.Nm , 174which deletes all redirected routes 175through the gateway involved, advances the age of all RIP routes through 176the gateway to allow an alternate to be chosen, and advances of the 177age of any relevant Router Discovery Protocol default routes. 178.Pp 179Hosts acting as internetwork routers gratuitously supply their 180routing tables every 30 seconds to all directly connected hosts 181and networks. 182These RIP responses are sent to the broadcast address on nets that support 183broadcasting, 184to the destination address on point-to-point links, and to the router's 185own address on other networks. 186If RIPv2 is enabled, multicast packets are sent on interfaces that 187support multicasting. 188.Pp 189If no response is received on a remote interface, if there are errors 190while sending responses, 191or if there are more errors than input or output (see 192.Xr netstat 1 ) , 193then the cable or some other part of the interface is assumed to be 194disconnected or broken, and routes are adjusted appropriately. 195.Pp 196The 197.Em Internet Router Discovery Protocol 198is handled similarly. 199When the daemon is supplying RIP routes, it also listens for 200Router Discovery Solicitations and sends Advertisements. 201When it is quiet and listening to other RIP routers, it 202sends Solicitations and listens for Advertisements. 203If it receives 204a good Advertisement and it is not multi-homed, 205it stops listening for broadcast or multicast RIP responses. 206It tracks several advertising routers to speed recovery when the 207currently chosen router dies. 208If all discovered routers disappear, 209the daemon resumes listening to RIP responses. 210It continues listening to RIP while using Router Discovery 211if multi-homed to ensure all interfaces are used. 212.Pp 213The Router Discovery standard requires that advertisements 214have a default "lifetime" of 30 minutes. 215That means should 216something happen, a client can be without a good route for 21730 minutes. 218It is a good idea to reduce the default to 45 219seconds using 220.Fl P Cm rdisc_interval=45 221on the command line or 222.Cm rdisc_interval=45 223in the 224.Pa /etc/gateways 225file. 226.Pp 227While using Router Discovery (which happens by default when 228the system has a single network interface and a Router Discover Advertisement 229is received), there is a single default route and a variable number of 230redirected host routes in the kernel table. 231On a host with more than one network interface, 232this default route will be via only one of the interfaces. 233Thus, multi-homed hosts running with 234.Fl q 235might need 236.Cm no_rdisc 237described below. 238.Pp 239See the 240.Cm pm_rdisc 241facility described below to support "legacy" systems 242that can handle neither RIPv2 nor Router Discovery. 243.Pp 244By default, neither Router Discovery advertisements nor solicitations 245are sent over point to point links (e.g.\& PPP). 246The netmask associated with point-to-point links (such as SLIP 247or PPP, with the IFF_POINTOPOINT flag) is used by 248.Nm 249to infer the netmask used by the remote system when RIPv1 is used. 250.Pp 251The following options are available: 252.Bl -tag -width indent 253.It Fl s 254force 255.Nm 256to supply routing information. 257This is the default if multiple network interfaces are present on which 258RIP or Router Discovery have not been disabled, and if the kernel switch 259ipforwarding=1. 260.It Fl q 261is the opposite of the 262.Fl s 263option. 264This is the default when only one interface is present. 265With this explicit option, the daemon is always in "quiet-mode" for RIP 266and does not supply routing information to other computers. 267.It Fl d 268do not run in the background. 269This option is meant for interactive use. 270.It Fl g 271used on internetwork routers to offer a route 272to the "default" destination. 273It is equivalent to 274.Fl F 275.Cm 0/0,1 276and is present mostly for historical reasons. 277A better choice is 278.Fl P Cm pm_rdisc 279on the command line or 280.Cm pm_rdisc 281in the 282.Pa /etc/gateways 283file, 284since a larger metric 285will be used, reducing the spread of the potentially dangerous 286default route. 287This is typically used on a gateway to the Internet, 288or on a gateway that uses another routing protocol whose routes 289are not reported to other local routers. 290Notice that because a metric of 1 is used, this feature is 291dangerous. 292It is more commonly accidentally used to create chaos with a 293routing loop than to solve problems. 294.It Fl h 295cause host or point-to-point routes to not be advertised, 296provided there is a network route going the same direction. 297That is a limited kind of aggregation. 298This option is useful on gateways to Ethernets that have other gateway 299machines connected with point-to-point links such as SLIP. 300.It Fl m 301cause the machine to advertise a host or point-to-point route to 302its primary interface. 303It is useful on multi-homed machines such as NFS servers. 304This option should not be used except when the cost of 305the host routes it generates is justified by the popularity of 306the server. 307It is effective only when the machine is supplying 308routing information, because there is more than one interface. 309The 310.Fl m 311option overrides the 312.Fl q 313option to the limited extent of advertising the host route. 314.It Fl A 315do not ignore RIPv2 authentication if we do not care about RIPv2 316authentication. 317This option is required for conformance with RFC 1723. 318However, it makes no sense and breaks using RIP as a discovery protocol 319to ignore all RIPv2 packets that carry authentication when this machine 320does not care about authentication. 321.It Fl t 322increase the debugging level, which causes more information to be logged 323on the tracefile specified with 324.Fl T 325or standard out. 326The debugging level can be increased or decreased 327with the 328.Em SIGUSR1 329or 330.Em SIGUSR2 331signals or with the 332.Xr rtquery 8 333command. 334.It Fl T Ar tracefile 335increases the debugging level to at least 1 and 336causes debugging information to be appended to the trace file. 337Note that because of security concerns, it is wisest to not run 338.Nm 339routinely with tracing directed to a file. 340.It Fl v 341display and logs the version of daemon. 342.It Fl F Ar net[/mask][,metric] 343minimize routes in transmissions via interfaces with addresses that match 344.Em net/mask , 345and synthesizes a default route to this machine with the 346.Em metric . 347The intent is to reduce RIP traffic on slow, point-to-point links 348such as PPP links by replacing many large UDP packets of RIP information 349with a single, small packet containing a "fake" default route. 350If 351.Em metric 352is absent, a value of 14 is assumed to limit 353the spread of the "fake" default route. 354This is a dangerous feature that when used carelessly can cause routing 355loops. 356Notice also that more than one interface can match the specified network 357number and mask. 358See also 359.Fl g . 360.It Fl P Ar parms 361is equivalent to adding the parameter 362line 363.Em parms 364to the 365.Pa /etc/gateways 366file. 367.El 368.Pp 369Any other argument supplied is interpreted as the name 370of a file in which the actions of 371.Nm 372should be logged. 373It is better to use 374.Fl T 375instead of 376appending the name of the trace file to the command. 377.Pp 378The 379.Nm 380utility also supports the notion of 381"distant" 382.Em passive 383or 384.Em active 385gateways. 386When 387.Nm 388is started, it reads the file 389.Pa /etc/gateways 390to find such distant gateways which may not be located using 391only information from a routing socket, to discover if some 392of the local gateways are 393.Em passive , 394and to obtain other parameters. 395Gateways specified in this manner should be marked passive 396if they are not expected to exchange routing information, 397while gateways marked active 398should be willing to exchange RIP packets. 399Routes through 400.Em passive 401gateways are installed in the 402kernel's routing tables once upon startup and are not included in 403transmitted RIP responses. 404.Pp 405Distant active gateways are treated like network interfaces. 406RIP responses are sent 407to the distant 408.Em active 409gateway. 410If no responses are received, the associated route is deleted from 411the kernel table and RIP responses advertised via other interfaces. 412If the distant gateway resumes sending RIP responses, the associated 413route is restored. 414.Pp 415Such gateways can be useful on media that do not support broadcasts 416or multicasts but otherwise act like classic shared media like 417Ethernets such as some ATM networks. 418One can list all RIP routers reachable on the HIPPI or ATM network in 419.Pa /etc/gateways 420with a series of 421"host" lines. 422Note that it is usually desirable to use RIPv2 in such situations 423to avoid generating lists of inferred host routes. 424.Pp 425Gateways marked 426.Em external 427are also passive, but are not placed in the kernel 428routing table nor are they included in routing updates. 429The function of external entries is to indicate 430that another routing process 431will install such a route if necessary, 432and that other routes to that destination should not be installed 433by 434.Nm . 435Such entries are only required when both routers may learn of routes 436to the same destination. 437.Pp 438The 439.Pa /etc/gateways 440file is comprised of a series of lines, each in 441one of the following two formats or consist of parameters described later. 442Blank lines and lines starting with '#' are comments. 443.Pp 444.Bd -ragged 445.Cm net 446.Ar Nname[/mask] 447.Cm gateway 448.Ar Gname 449.Cm metric 450.Ar value 451.Pf < Cm passive No \&| 452.Cm active No \&| 453.Cm extern Ns > 454.Ed 455.Bd -ragged 456.Cm host 457.Ar Hname 458.Cm gateway 459.Ar Gname 460.Cm metric 461.Ar value 462.Pf < Cm passive No \&| 463.Cm active No \&| 464.Cm extern Ns > 465.Ed 466.Pp 467.Ar Nname 468or 469.Ar Hname 470is the name of the destination network or host. 471It may be a symbolic network name or an Internet address 472specified in "dot" notation (see 473.Xr inet 3 ) . 474(If it is a name, then it must either be defined in 475.Pa /etc/networks 476or 477.Pa /etc/hosts , 478or 479.Xr named 8 , 480must have been started before 481.Nm . ) 482.Pp 483.Ar Mask 484is an optional number between 1 and 32 indicating the netmask associated 485with 486.Ar Nname . 487.Pp 488.Ar Gname 489is the name or address of the gateway to which RIP responses should 490be forwarded. 491.Pp 492.Ar Value 493is the hop count to the destination host or network. 494.Pp 495.Cm Host Ar hname 496is equivalent to 497.Cm net Ar nname/32 . 498.Pp 499One of the keywords 500.Cm passive , 501.Cm active 502or 503.Cm external 504must be present to indicate whether the gateway should be treated as 505.Cm passive 506or 507.Cm active 508(as described above), 509or whether the gateway is 510.Cm external 511to the scope of the RIP protocol. 512.Pp 513As can be seen when debugging is turned on with 514.Fl t , 515such lines create pseudo-interfaces. 516To set parameters for remote or external interfaces, 517a line starting with 518.Cm if=alias(Hname) , 519.Cm if=remote(Hname) , 520etc.\& should be used. 521.Ss Parameters 522Lines that start with neither "net" nor "host" must consist of one 523or more of the following parameter settings, separated by commas or 524blanks: 525.Bl -tag -width indent 526.It Cm if Ns = Ns Ar ifname 527indicates that the other parameters on the line apply to the interface 528name 529.Ar ifname . 530.It Cm subnet Ns = Ns Ar nname Ns Oo / Ns Ar mask Oc Ns Op , Ns Ar metric 531advertises a route to network 532.Ar nname 533with mask 534.Ar mask 535and the supplied metric (default 1). 536This is useful for filling "holes" in CIDR allocations. 537This parameter must appear by itself on a line. 538The network number must specify a full, 32-bit value, as in 192.0.2.0 539instead of 192.0.2. 540.Pp 541Do not use this feature unless necessary. 542It is dangerous. 543.It Cm ripv1_mask Ns = Ns Ar nname Ns / Ns Ar mask1 , Ns Ar mask2 544specifies that netmask of the network of which 545.Ar nname Ns / Ns Ar mask1 546is 547a subnet should be 548.Ar mask2 . 549For example, 550.Dq Li ripv1_mask=192.0.2.16/28,27 551marks 192.0.2.16/28 552as a subnet of 192.0.2.0/27 instead of 192.0.2.0/24. 553It is better to turn on RIPv2 instead of using this facility, for example 554with 555.Cm ripv2_out . 556.It Cm passwd Ns = Ns Ar XXX[|KeyID[start|stop]] 557specifies a RIPv2 cleartext password that will be included on 558all RIPv2 responses sent, and checked on all RIPv2 responses received. 559Any blanks, tab characters, commas, or '#', '|', or NULL characters in the 560password must be escaped with a backslash (\\). 561The common escape sequences \\n, \\r, \\t, \\b, and \\xxx have their 562usual meanings. 563The 564.Cm KeyID 565must be unique but is ignored for cleartext passwords. 566If present, 567.Cm start 568and 569.Cm stop 570are timestamps in the form year/month/day@hour:minute. 571They specify when the password is valid. 572The valid password with the most future is used on output packets, unless 573all passwords have expired, in which case the password that expired most 574recently is used, or unless no passwords are valid yet, in which case 575no password is output. 576Incoming packets can carry any password that is valid, will 577be valid within the next 24 hours, or that was valid within the preceding 57824 hours. 579To protect the secrets, the passwd settings are valid only in the 580.Em /etc/gateways 581file and only when that file is readable only by UID 0. 582.It Cm md5_passwd Ns \&= Ns Ar XXX|KeyID[start|stop] 583specifies a RIPv2 MD5 password. 584Except that a 585.Cm KeyID 586is required, this keyword is similar to 587.Cm passwd . 588.It Cm no_ag 589turns off aggregation of subnets in RIPv1 and RIPv2 responses. 590.It Cm no_super_ag 591turns off aggregation of networks into supernets in RIPv2 responses. 592.It Cm passive 593marks the interface to not be advertised in updates sent via other 594interfaces, and turns off all RIP and router discovery through the interface. 595.It Cm no_rip 596disables all RIP processing on the specified interface. 597If no interfaces are allowed to process RIP packets, 598.Nm 599acts purely as a router discovery daemon. 600.Pp 601Note that turning off RIP without explicitly turning on router 602discovery advertisements with 603.Cm rdisc_adv 604or 605.Fl s 606causes 607.Nm 608to act as a client router discovery daemon, not advertising. 609.It Cm no_rip_mcast 610causes RIPv2 packets to be broadcast instead of multicast. 611.It Cm no_rip_out 612causes no RIP updates to be sent. 613.It Cm no_ripv1_in 614causes RIPv1 received responses to be ignored. 615.It Cm no_ripv2_in 616causes RIPv2 received responses to be ignored. 617.It Cm ripv2_out 618turns on RIPv2 output and causes RIPv2 advertisements to be 619multicast when possible. 620.It Cm ripv2 621is equivalent to 622.Cm no_ripv1_in 623and 624.Cm no_ripv1_out . 625This enables RIPv2. 626.It Cm no_rdisc 627disables the Internet Router Discovery Protocol. 628.It Cm no_solicit 629disables the transmission of Router Discovery Solicitations. 630.It Cm send_solicit 631specifies that Router Discovery solicitations should be sent, 632even on point-to-point links, 633which by default only listen to Router Discovery messages. 634.It Cm no_rdisc_adv 635disables the transmission of Router Discovery Advertisements. 636.It Cm rdisc_adv 637specifies that Router Discovery Advertisements should be sent, 638even on point-to-point links, 639which by default only listen to Router Discovery messages. 640.It Cm bcast_rdisc 641specifies that Router Discovery packets should be broadcast instead of 642multicast. 643.It Cm rdisc_pref Ns \&= Ns Ar N 644sets the preference in Router Discovery Advertisements to the optionally 645signed integer 646.Ar N . 647The default preference is 0. 648Default routes with smaller or more negative preferences are preferred by 649clients. 650.It Cm rdisc_interval Ns \&= Ns Ar N 651sets the nominal interval with which Router Discovery Advertisements 652are transmitted to N seconds and their lifetime to 3*N. 653.It Cm fake_default Ns \&= Ns Ar metric 654has an identical effect to 655.Fl F Ar net[/mask][=metric] 656with the network and mask coming from the specified interface. 657.It Cm pm_rdisc 658is similar to 659.Cm fake_default . 660When RIPv2 routes are multicast, so that RIPv1 listeners cannot 661receive them, this feature causes a RIPv1 default route to be 662broadcast to RIPv1 listeners. 663Unless modified with 664.Cm fake_default , 665the default route is broadcast with a metric of 14. 666That serves as a "poor man's router discovery" protocol. 667.It Cm adj_inmetric Ns \&= Ns Ar delta 668adjusts the hop count or metric of received RIP routes by 669.Ar delta . 670The metric of every received RIP route is increased by the sum 671of two values associated with the interface. 672One is the adj_inmetric value and the other is the interface 673metric set with 674.Xr ifconfig 8 . 675.It Cm adj_outmetric Ns \&= Ns Ar delta 676adjusts the hop count or metric of advertised RIP routes by 677.Ar delta . 678The metric of every received RIP route is increased by the metric 679associated with the interface by which it was received, or by 1 if 680the interface does not have a non-zero metric. 681The metric of the received route is then increased by the 682adj_outmetric associated with the interface. 683Every advertised route is increased by a total of four 684values, 685the metric set for the interface by which it was received with 686.Xr ifconfig 8 , 687the 688.Cm adj_inmetric Ar delta 689of the receiving interface, 690the metric set for the interface by which it is transmitted with 691.Xr ifconfig 8 , 692and the 693.Cm adj_outmetric Ar delta 694of the transmitting interface. 695.It Cm trust_gateway Ns \&= Ns Ar rname[|net1/mask1|net2/mask2|...] 696causes RIP packets from router 697.Ar rname 698and other routers named in other 699.Cm trust_gateway 700keywords to be accepted, and packets from other routers to be ignored. 701If networks are specified, then routes to other networks will be ignored 702from that router. 703.It Cm redirect_ok 704allows the kernel to listen ICMP Redirect messages when the system is acting 705as a router and forwarding packets. 706Otherwise, ICMP Redirect messages are overridden and deleted when the 707system is acting as a router. 708.El 709.Sh FILES 710.Bl -tag -width /etc/gateways -compact 711.It Pa /etc/gateways 712for distant gateways 713.El 714.Sh SEE ALSO 715.Xr icmp 4 , 716.Xr udp 4 , 717.Xr rtquery 8 718.Rs 719.%T Internet Transport Protocols 720.%R XSIS 028112 721.%Q Xerox System Integration Standard 722.Re 723.Sh HISTORY 724The 725.Nm 726utility appeared in 727.Bx 4.2 . 728.\" LocalWords: loopback ICMP rtquery ifconfig multicasting Solicitations RIPv 729.\" LocalWords: netstat rdisc 730.Sh BUGS 731It does not always detect unidirectional failures in network interfaces, 732for example, when the output side fails. 733