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