Import Upstream version 1.2.2
[quagga-debian.git] / doc / ripd.texi
1 @c -*-texinfo-*-
2 @c This is part of the Quagga Manual.
3 @c @value{COPYRIGHT_STR}
4 @c See file quagga.texi for copying conditions.
5 @node RIP
6 @chapter RIP
7
8 RIP -- Routing Information Protocol is widely deployed interior gateway
9 protocol.  RIP was developed in the 1970s at Xerox Labs as part of the
10 XNS routing protocol.  RIP is a @dfn{distance-vector} protocol and is
11 based on the @dfn{Bellman-Ford} algorithms.  As a distance-vector
12 protocol, RIP router send updates to its neighbors periodically, thus
13 allowing the convergence to a known topology.  In each update, the
14 distance to any given network will be broadcasted to its neighboring
15 router.
16
17 @command{ripd} supports RIP version 2 as described in RFC2453 and RIP
18 version 1 as described in RFC1058.
19
20 @menu
21 * Starting and Stopping ripd::  
22 * RIP Configuration::           
23 * RIP Version Control::
24 * How to Announce RIP route::   
25 * Filtering RIP Routes::        
26 * RIP Metric Manipulation::     
27 * RIP distance::                
28 * RIP route-map::               
29 * RIP Authentication::          
30 * RIP Timers::                  
31 * Show RIP Information::        
32 * RIP Debug Commands::          
33 @end menu
34
35 @node Starting and Stopping ripd
36 @section Starting and Stopping ripd
37
38 The default configuration file name of @command{ripd}'s is
39 @file{ripd.conf}.  When invocation @command{ripd} searches directory
40 @value{INSTALL_PREFIX_ETC}.  If @file{ripd.conf} is not there next
41 search current directory.
42
43 RIP uses UDP port 520 to send and receive RIP packets.  So the user must have
44 the capability to bind the port, generally this means that the user must
45 have superuser privileges.  RIP protocol requires interface information
46 maintained by @command{zebra} daemon.  So running @command{zebra}
47 is mandatory to run @command{ripd}.  Thus minimum sequence for running
48 RIP is like below:
49
50 @example
51 @group
52 # zebra -d
53 # ripd -d
54 @end group
55 @end example
56
57 Please note that @command{zebra} must be invoked before @command{ripd}.
58
59 To stop @command{ripd}.  Please use @command{kill `cat
60 /var/run/ripd.pid`}.  Certain signals have special meaningss to @command{ripd}.
61
62 @table @samp
63 @item SIGHUP
64 Reload configuration file @file{ripd.conf}.  All configurations are
65 reseted.  All routes learned so far are cleared and removed from routing
66 table.
67 @item SIGUSR1
68 Rotate @command{ripd} logfile.
69 @item SIGINT
70 @itemx SIGTERM
71 @command{ripd} sweeps all installed RIP routes then terminates properly.
72 @end table
73
74 @command{ripd} invocation options.  Common options that can be specified
75 (@pxref{Common Invocation Options}).
76
77 @table @samp
78 @item -r
79 @itemx --retain
80 When the program terminates, retain routes added by @command{ripd}.
81 @end table
82
83 @menu
84 * RIP netmask::                 
85 @end menu
86
87 @node RIP netmask
88 @subsection RIP netmask
89
90 The netmask features of @command{ripd} support both version 1 and version 2 of
91 RIP.  Version 1 of RIP originally contained no netmask information.  In
92 RIP version 1, network classes were originally used to determine the
93 size of the netmask.  Class A networks use 8 bits of mask, Class B
94 networks use 16 bits of masks, while Class C networks use 24 bits of
95 mask.  Today, the most widely used method of a network mask is assigned
96 to the packet on the basis of the interface that received the packet.
97 Version 2 of RIP supports a variable length subnet mask (VLSM).  By
98 extending the subnet mask, the mask can be divided and reused.  Each
99 subnet can be used for different purposes such as large to middle size
100 LANs and WAN links.  Quagga @command{ripd} does not support the non-sequential
101 netmasks that are included in RIP Version 2.
102
103 In a case of similar information with the same prefix and metric, the
104 old information will be suppressed.  Ripd does not currently support
105 equal cost multipath routing.
106
107
108 @node RIP Configuration
109 @section RIP Configuration
110
111 @deffn Command {router rip} {}
112 The @code{router rip} command is necessary to enable RIP.  To disable
113 RIP, use the @code{no router rip} command.  RIP must be enabled before
114 carrying out any of the RIP commands.
115 @end deffn
116
117 @deffn Command {no router rip} {}
118 Disable RIP.
119 @end deffn
120
121 @deffn {RIP Command} {network @var{network}} {}
122 @deffnx {RIP Command} {no network @var{network}} {}
123 Set the RIP enable interface by @var{network}.  The interfaces which
124 have addresses matching with @var{network} are enabled.
125
126 This group of commands either enables or disables RIP interfaces between
127 certain numbers of a specified network address.  For example, if the
128 network for 10.0.0.0/24 is RIP enabled, this would result in all the
129 addresses from 10.0.0.0 to 10.0.0.255 being enabled for RIP.  The @code{no
130 network} command will disable RIP for the specified network.
131 @end deffn
132
133 @deffn {RIP Command} {network @var{ifname}} {}
134 @deffnx {RIP Command} {no network @var{ifname}} {}
135 Set a RIP enabled interface by @var{ifname}.  Both the sending and
136 receiving of RIP packets will be enabled on the port specified in the
137 @code{network ifname} command.  The @code{no network ifname} command will disable
138 RIP on the specified interface.
139 @end deffn
140
141 @deffn {RIP Command} {neighbor @var{a.b.c.d}} {}
142 @deffnx {RIP Command} {no neighbor @var{a.b.c.d}} {}
143 Specify RIP neighbor.  When a neighbor doesn't understand multicast,
144 this command is used to specify neighbors.  In some cases, not all
145 routers will be able to understand multicasting, where packets are sent
146 to a network or a group of addresses.  In a situation where a neighbor
147 cannot process multicast packets, it is necessary to establish a direct
148 link between routers.  The neighbor command allows the network
149 administrator to specify a router as a RIP neighbor.  The @code{no
150 neighbor a.b.c.d} command will disable the RIP neighbor.
151 @end deffn
152
153 Below is very simple RIP configuration.  Interface @code{eth0} and
154 interface which address match to @code{10.0.0.0/8} are RIP enabled.
155
156 @example
157 @group
158 !
159 router rip
160  network 10.0.0.0/8
161  network eth0
162 !
163 @end group
164 @end example
165
166 Passive interface
167
168 @deffn {RIP command} {passive-interface (@var{IFNAME}|default)} {}
169 @deffnx {RIP command} {no passive-interface @var{IFNAME}} {}
170 This command sets the specified interface to passive mode.  On passive mode
171 interface, all receiving packets are processed as normal and ripd does
172 not send either multicast or unicast RIP packets except to RIP neighbors
173 specified with @code{neighbor} command. The interface may be specified
174 as @var{default} to make ripd default to passive on all interfaces. 
175
176 The default is to be passive on all interfaces.
177 @end deffn
178
179 RIP split-horizon
180
181 @deffn {Interface command} {ip split-horizon} {}
182 @deffnx {Interface command} {no ip split-horizon} {}
183 Control split-horizon on the interface.  Default is @code{ip
184 split-horizon}.  If you don't perform split-horizon on the interface,
185 please specify @code{no ip split-horizon}.
186 @end deffn
187
188 @node RIP Version Control
189 @section RIP Version Control
190
191 RIP can be configured to send either Version 1 or Version 2 packets.
192 The default is to send RIPv2 while accepting both RIPv1 and RIPv2 (and
193 replying with packets of the appropriate version for REQUESTS /
194 triggered updates). The version to receive and send can be specified
195 globally, and further overriden on a per-interface basis if needs be
196 for send and receive seperately (see below).
197
198 It is important to note that RIPv1 can not be authenticated. Further,
199 if RIPv1 is enabled then RIP will reply to REQUEST packets, sending the
200 state of its RIP routing table to any remote routers that ask on
201 demand. For a more detailed discussion on the security implications of
202 RIPv1 see @ref{RIP Authentication}.
203
204 @deffn {RIP Command} {version @var{version}} {}
205 Set RIP version to accept for reads and send.  @var{version}
206 can be either `1'' or `2''. 
207
208 Disabling RIPv1 by specifying version 2 is STRONGLY encouraged,
209 @xref{RIP Authentication}. This may become the default in a future
210 release.
211
212 Default: Send Version 2, and accept either version.
213 @end deffn
214
215 @deffn {RIP Command} {no version} {}
216 Reset the global version setting back to the default.
217 @end deffn
218
219 @deffn {Interface command} {ip rip send version @var{version}} {}
220 @var{version} can be `1', `2' or `1 2'.
221
222 This interface command overrides the global rip version setting, and
223 selects which version of RIP to send packets with, for this interface
224 specifically. Choice of RIP Version 1, RIP Version 2, or both versions. 
225 In the latter case, where `1 2' is specified, packets will be both
226 broadcast and multicast.
227
228 Default: Send packets according to the global version (version 2)
229 @end deffn
230
231 @deffn {Interface command} {ip rip receive version @var{version}} {}
232 @var{version} can be `1', `2' or `1 2'.
233
234 This interface command overrides the global rip version setting, and
235 selects which versions of RIP packets will be accepted on this
236 interface. Choice of RIP Version 1, RIP Version 2, or both.
237
238 Default: Accept packets according to the global setting (both 1 and 2).
239 @end deffn
240
241 @node How to Announce RIP route
242 @section How to Announce RIP route
243
244 @deffn {RIP command} {redistribute kernel} {}
245 @deffnx {RIP command} {redistribute kernel metric <0-16>} {}
246 @deffnx {RIP command} {redistribute kernel route-map @var{route-map}} {}
247 @deffnx {RIP command} {no redistribute kernel} {}
248 @code{redistribute kernel} redistributes routing information from
249 kernel route entries into the RIP tables. @code{no redistribute kernel}
250 disables the routes.
251 @end deffn
252
253 @deffn {RIP command} {redistribute static} {}
254 @deffnx {RIP command} {redistribute static metric <0-16>} {}
255 @deffnx {RIP command} {redistribute static route-map @var{route-map}} {}
256 @deffnx {RIP command} {no redistribute static} {}
257 @code{redistribute static} redistributes routing information from
258 static route entries into the RIP tables. @code{no redistribute static}
259 disables the routes.
260 @end deffn
261
262 @deffn {RIP command} {redistribute connected} {}
263 @deffnx {RIP command} {redistribute connected metric <0-16>} {}
264 @deffnx {RIP command} {redistribute connected route-map @var{route-map}} {}
265 @deffnx {RIP command} {no redistribute connected} {}
266 Redistribute connected routes into the RIP tables.  @code{no
267 redistribute connected} disables the connected routes in the RIP tables.
268 This command redistribute connected of the interface which RIP disabled.
269 The connected route on RIP enabled interface is announced by default.
270 @end deffn
271
272 @deffn {RIP command} {redistribute ospf} {}
273 @deffnx {RIP command} {redistribute ospf metric <0-16>} {}
274 @deffnx {RIP command} {redistribute ospf route-map @var{route-map}} {}
275 @deffnx {RIP command} {no redistribute ospf} {}
276 @code{redistribute ospf} redistributes routing information from
277 ospf route entries into the RIP tables. @code{no redistribute ospf}
278 disables the routes.
279 @end deffn
280
281 @deffn {RIP command} {redistribute bgp} {}
282 @deffnx {RIP command} {redistribute bgp metric <0-16>} {}
283 @deffnx {RIP command} {redistribute bgp route-map @var{route-map}} {}
284 @deffnx {RIP command} {no redistribute bgp} {}
285 @code{redistribute bgp} redistributes routing information from
286 bgp route entries into the RIP tables. @code{no redistribute bgp}
287 disables the routes.
288 @end deffn
289
290 If you want to specify RIP only static routes:
291
292 @deffn {RIP command} {default-information originate} {}
293 @end deffn
294
295 @deffn {RIP command} {route @var{a.b.c.d/m}} {}
296 @deffnx {RIP command} {no route @var{a.b.c.d/m}} {}
297 This command is specific to Quagga.  The @code{route} command makes a static
298 route only inside RIP. This command should be used only by advanced
299 users who are particularly knowledgeable about the RIP protocol.  In
300 most cases, we recommend creating a static route in Quagga and
301 redistributing it in RIP using @code{redistribute static}.
302 @end deffn
303
304 @node  Filtering RIP Routes
305 @section Filtering RIP Routes
306
307 RIP routes can be filtered by a distribute-list.
308
309 @deffn Command {distribute-list @var{access_list} @var{direct} @var{ifname}} {}
310 You can apply access lists to the interface with a @code{distribute-list}
311 command.  @var{access_list} is the access list name.  @var{direct} is
312 @samp{in} or @samp{out}.  If @var{direct} is @samp{in} the access list
313 is applied to input packets.
314
315 The @code{distribute-list} command can be used to filter the RIP path.
316 @code{distribute-list} can apply access-lists to a chosen interface.
317 First, one should specify the access-list.  Next, the name of the
318 access-list is used in the distribute-list command.  For example, in the
319 following configuration @samp{eth0} will permit only the paths that
320 match the route 10.0.0.0/8
321
322 @example
323 @group
324 !
325 router rip
326  distribute-list private in eth0
327 !
328 access-list private permit 10 10.0.0.0/8
329 access-list private deny any
330 !
331 @end group
332 @end example
333 @end deffn
334
335 @code{distribute-list} can be applied to both incoming and outgoing data.
336
337 @deffn Command {distribute-list prefix @var{prefix_list} (in|out) @var{ifname}} {}
338 You can apply prefix lists to the interface with a
339 @code{distribute-list} command.  @var{prefix_list} is the prefix list
340 name.  Next is the direction of @samp{in} or @samp{out}.  If
341 @var{direct} is @samp{in} the access list is applied to input packets.
342 @end deffn
343
344 @node RIP Metric Manipulation
345 @section RIP Metric Manipulation
346
347 RIP metric is a value for distance for the network.  Usually
348 @command{ripd} increment the metric when the network information is
349 received.  Redistributed routes' metric is set to 1.
350
351 @deffn {RIP command} {default-metric <1-16>} {}
352 @deffnx {RIP command} {no default-metric <1-16>} {}
353 This command modifies the default metric value for redistributed routes.  The
354 default value is 1.  This command does not affect connected route
355 even if it is redistributed by @command{redistribute connected}.  To modify
356 connected route's metric value, please use @command{redistribute
357 connected metric} or @command{route-map}.  @command{offset-list} also
358 affects connected routes.
359 @end deffn
360
361 @deffn {RIP command} {offset-list @var{access-list} (in|out)} {}
362 @deffnx {RIP command} {offset-list @var{access-list} (in|out) @var{ifname}} {}
363 @end deffn
364
365 @node RIP distance
366 @section RIP distance
367
368 Distance value is used in zebra daemon.  Default RIP distance is 120.
369
370 @deffn {RIP command} {distance <1-255>} {}
371 @deffnx {RIP command} {no distance <1-255>} {}
372 Set default RIP distance to specified value.
373 @end deffn
374
375 @deffn {RIP command} {distance <1-255> @var{A.B.C.D/M}} {}
376 @deffnx {RIP command} {no distance <1-255> @var{A.B.C.D/M}} {}
377 Set default RIP distance to specified value when the route's source IP
378 address matches the specified prefix.
379 @end deffn
380
381 @deffn {RIP command} {distance <1-255> @var{A.B.C.D/M} @var{access-list}} {}
382 @deffnx {RIP command} {no distance <1-255> @var{A.B.C.D/M} @var{access-list}} {}
383 Set default RIP distance to specified value when the route's source IP
384 address matches the specified prefix and the specified access-list.
385 @end deffn
386
387 @node RIP route-map
388 @section RIP route-map
389
390 Usage of @command{ripd}'s route-map support.
391
392 Optional argument route-map MAP_NAME can be added to each @code{redistribute}
393 statement.
394
395 @example
396 redistribute static [route-map MAP_NAME]
397 redistribute connected [route-map MAP_NAME]
398 .....
399 @end example
400
401 Cisco applies route-map _before_ routes will exported to rip route table. 
402 In current Quagga's test implementation, @command{ripd} applies route-map
403 after routes are listed in the route table and before routes will be
404 announced to an interface (something like output filter). I think it is not
405 so clear, but it is draft and it may be changed at future.
406
407 Route-map statement (@pxref{Route Map}) is needed to use route-map
408 functionality.
409
410 @deffn {Route Map} {match interface @var{word}} {}
411 This command match to incoming interface.  Notation of this match is
412 different from Cisco. Cisco uses a list of interfaces - NAME1 NAME2
413 ... NAMEN.  Ripd allows only one name (maybe will change in the
414 future).  Next - Cisco means interface which includes next-hop of
415 routes (it is somewhat similar to "ip next-hop" statement).  Ripd
416 means interface where this route will be sent. This difference is
417 because "next-hop" of same routes which sends to different interfaces
418 must be different. Maybe it'd be better to made new matches - say
419 "match interface-out NAME" or something like that.
420 @end deffn
421
422 @deffn {Route Map} {match ip address @var{word}} {}
423 @deffnx {Route Map} {match ip address prefix-list @var{word}} {}
424 Match if route destination is permitted by access-list.
425 @end deffn
426
427 @deffn {Route Map} {match ip next-hop @var{word}} {}
428 @deffnx {Route Map} {match ip next-hop prefix-list @var{word}} {}
429 Match if route next-hop (meaning next-hop listed in the rip route-table
430 as displayed by "show ip rip") is permitted by access-list.
431 @end deffn
432
433 @deffn {Route Map} {match metric <0-4294967295>} {}
434 This command match to the metric value of RIP updates.  For other
435 protocol compatibility metric range is shown as <0-4294967295>.  But
436 for RIP protocol only the value range <0-16> make sense.
437 @end deffn
438
439 @deffn {Route Map} {set ip next-hop A.B.C.D} {}
440 This command set next hop value in RIPv2 protocol.  This command does
441 not affect RIPv1 because there is no next hop field in the packet.
442 @end deffn
443
444 @deffn {Route Map} {set metric <0-4294967295>} {}
445 Set a metric for matched route when sending announcement.  The metric
446 value range is very large for compatibility with other protocols.  For
447 RIP, valid metric values are from 1 to 16.
448 @end deffn
449
450 @node RIP Authentication
451 @section RIP Authentication
452
453 RIPv2 allows packets to be authenticated via either an insecure plain
454 text password, included with the packet, or via a more secure MD5 based
455 @acronym{HMAC, keyed-Hashing for Message AuthentiCation},
456 RIPv1 can not be authenticated at all, thus when authentication is
457 configured @code{ripd} will discard routing updates received via RIPv1
458 packets.
459
460 However, unless RIPv1 reception is disabled entirely, 
461 @xref{RIP Version Control}, RIPv1 REQUEST packets which are received,
462 which query the router for routing information, will still be honoured
463 by @code{ripd}, and @code{ripd} WILL reply to such packets. This allows 
464 @code{ripd} to honour such REQUESTs (which sometimes is used by old
465 equipment and very simple devices to bootstrap their default route),
466 while still providing security for route updates which are received.
467
468 In short: Enabling authentication prevents routes being updated by
469 unauthenticated remote routers, but still can allow routes (I.e. the
470 entire RIP routing table) to be queried remotely, potentially by anyone
471 on the internet, via RIPv1.
472
473 To prevent such unauthenticated querying of routes disable RIPv1,
474 @xref{RIP Version Control}.
475
476 @deffn {Interface command} {ip rip authentication mode md5} {}
477 @deffnx {Interface command} {no ip rip authentication mode md5} {}
478 Set the interface with RIPv2 MD5 authentication.
479 @end deffn
480
481 @deffn {Interface command} {ip rip authentication mode text} {}
482 @deffnx {Interface command} {no ip rip authentication mode text} {}
483 Set the interface with RIPv2 simple password authentication.
484 @end deffn
485
486 @deffn {Interface command} {ip rip authentication string @var{string}} {}
487 @deffnx {Interface command} {no ip rip authentication string @var{string}} {}
488 RIP version 2 has simple text authentication.  This command sets
489 authentication string.  The string must be shorter than 16 characters.
490 @end deffn
491
492 @deffn {Interface command} {ip rip authentication key-chain @var{key-chain}} {}
493 @deffnx {Interface command} {no ip rip authentication key-chain @var{key-chain}} {}
494 Specifiy Keyed MD5 chain.
495 @end deffn
496
497 @example
498 !
499 key chain test
500  key 1
501   key-string test
502 !
503 interface eth1
504  ip rip authentication mode md5
505  ip rip authentication key-chain test
506 !
507 @end example
508
509 @node RIP Timers
510 @section RIP Timers
511
512 @deffn {RIP command} {timers basic @var{update} @var{timeout} @var{garbage}} {}
513
514 RIP protocol has several timers.  User can configure those timers' values
515 by @code{timers basic} command.
516
517 The default settings for the timers are as follows: 
518
519 @itemize @bullet 
520 @item
521 The update timer is 30 seconds. Every update timer seconds, the RIP
522 process is awakened to send an unsolicited Response message containing
523 the complete routing table to all neighboring RIP routers.
524
525 @item
526 The timeout timer is 180 seconds. Upon expiration of the timeout, the
527 route is no longer valid; however, it is retained in the routing table
528 for a short time so that neighbors can be notified that the route has
529 been dropped.
530
531 @item
532 The garbage collect timer is 120 seconds.  Upon expiration of the
533 garbage-collection timer, the route is finally removed from the routing
534 table.
535
536 @end itemize
537
538 The @code{timers basic} command allows the the default values of the timers
539 listed above to be changed.
540 @end deffn
541
542 @deffn {RIP command} {no timers basic} {}
543 The @code{no timers basic} command will reset the timers to the default
544 settings listed above.
545 @end deffn
546
547 @node Show RIP Information
548 @section Show RIP Information
549
550 To display RIP routes.
551
552 @deffn Command {show ip rip} {}
553 Show RIP routes.
554 @end deffn
555
556 The command displays all RIP routes. For routes that are received
557 through RIP, this command will display the time the packet was sent and
558 the tag information.  This command will also display this information
559 for routes redistributed into RIP.
560
561 @c Exmaple here.
562
563 @deffn Command {show ip rip status} {}
564 The command displays current RIP status.  It includes RIP timer,
565 filtering, version, RIP enabled interface and RIP peer inforation.
566 @end deffn
567
568 @example
569 @group
570 ripd> @b{show ip rip status}
571 Routing Protocol is "rip"
572   Sending updates every 30 seconds with +/-50%, next due in 35 seconds
573   Timeout after 180 seconds, garbage collect after 120 seconds
574   Outgoing update filter list for all interface is not set
575   Incoming update filter list for all interface is not set
576   Default redistribution metric is 1
577   Redistributing: kernel connected
578   Default version control: send version 2, receive version 2 
579     Interface        Send  Recv
580   Routing for Networks:
581     eth0
582     eth1
583     1.1.1.1
584     203.181.89.241
585   Routing Information Sources:
586     Gateway          BadPackets BadRoutes  Distance Last Update
587 @end group
588 @end example
589
590 @node RIP Debug Commands
591 @section RIP Debug Commands
592
593 Debug for RIP protocol.
594
595 @deffn Command {debug rip events} {}
596 Debug rip events.
597 @end deffn
598
599 @code{debug rip} will show RIP events.  Sending and receiving
600 packets, timers, and changes in interfaces are events shown with @command{ripd}.
601
602 @deffn Command {debug rip packet} {}
603 Debug rip packet.
604 @end deffn
605
606 @code{debug rip packet} will display detailed information about the RIP
607 packets.  The origin and port number of the packet as well as a packet
608 dump is shown.
609
610 @deffn Command {debug rip zebra} {}
611 Debug rip between zebra communication.
612 @end deffn
613
614 This command will show the communication between @command{ripd} and
615 @command{zebra}.  The main information will include addition and deletion of
616 paths to the kernel and the sending and receiving of interface information.
617
618 @deffn Command {show debugging rip} {}
619 Display @command{ripd}'s debugging option.
620 @end deffn
621
622 @code{show debugging rip} will show all information currently set for ripd
623 debug.