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