doc/pimd.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the Frr Manual.
   3 @c @value{COPYRIGHT_STR}
   4 @c See file frr.texi for copying conditions.
   5 @node PIM
   6 @chapter PIM
   7
   8 PIM -- Protocol Independent Multicast
   9
  10 @command{pimd} supports pim-sm as well as igmp v2 and v3.  pim is
  11 vrf aware and can work within the context of vrf's in order to
  12 do S,G mrouting.
  13
  14 @menu
  15 * Starting and Stopping pimd::
  16 * PIM Configuration::
  17 * PIM Interface Configuration::
  18 * PIM Multicast RIB insertion::
  19 * Show PIM Information::
  20 * PIM Debug Commands::
  21 @end menu
  22
  23 @node Starting and Stopping pimd
  24 @section Starting and Stopping pimd
  25
  26 The default configuration file name of @command{pimd}'s is
  27 @file{pimd.conf}.  When invocation @command{pimd} searches directory
  28 @value{INSTALL_PREFIX_ETC}.  If @file{pimd.conf} is not there
  29 then next search current directory.
  30
  31 @command{pimd} requires zebra for proper operation.  Additionally
  32 @command{pimd} depends on routing properly setup and working
  33 in the network that it is working on.
  34
  35 @example
  36 @group
  37 # zebra -d
  38 # pimd -d
  39 @end group
  40 @end example
  41
  42 Please note that @command{zebra} must be invoked before @command{pimd}.
  43
  44 To stop @command{pimd}.  Please use @command{kill `cat
  45 /var/run/pimd.pid`}.  Certain signals have special meanings to @command{pimd}.
  46
  47 @table @samp
  48 @item SIGUSR1
  49 Rotate @command{pimd} logfile.
  50 @item SIGINT
  51 @itemx SIGTERM
  52 @command{pimd} sweeps all installed PIM mroutes then terminates properly.
  53 @end table
  54
  55 @command{pimd} invocation options.  Common options that can be specified
  56 (@pxref{Common Invocation Options}).
  57
  58 @node PIM Configuration
  59
  60 @deffn Command {ip pim rp A.B.C.D A.B.C.D/M} {}
  61 In order to use pim, it is necessary to configure a RP for join
  62 messages to be sent to.  Currently the only methodology to
  63 do this is via static rp commands.  All routers in the
  64 pim network must agree on these values.  The first ip address
  65 is the RP's address and the second value is the matching
  66 prefix of group ranges covered.  This command is vrf aware,
  67 to configure for a vrf, enter the vrf submode.
  68 @end deffn
  69
  70 @deffn Command {ip pim spt-switchover infinity-and-beyond} {}
  71 On the last hop router if it is desired to not switch over
  72 to the SPT tree. Configure this command.  This command is
  73 vrf aware, to configure for a vrf, enter the vrf submode.
  74 #end deffn
  75
  76 @deffn Comand {ip pim ecmp} {}
  77 If pim has the a choice of ECMP nexthops for a particular
  78 RPF, pim will cause S,G flows to be spread out amongst
  79 the nexthops.  If this command is not specified then
  80 the first nexthop found will be used.  This command
  81 is vrf aware, to configure for a vrf, enter the vrf submode.
  82 @end deffn
  83
  84 @deffn Command {ip pim ecmp rebalance} {}
  85 If pim is using ECMP and an interface goes down, cause
  86 pim to rebalance all S,G flows aross the remaining
  87 nexthops.  If this command is not configured pim only
  88 modifies those S,G flows that were using the interface
  89 that went down.  This command is vrf aware, to configure
  90 for a vrf, enter the vrf submode.
  91 @end deffn
  92
  93 @deffn Command {ip pim join-prune-interval (60-600)} {}
  94 Modify the join/prune interval that pim uses to the
  95 new value.  Time is specified in seconds.  This command
  96 is vrf aware, to configure for a vrf, enter the vrf submode.
  97 @end deffn
  98
  99 @deffn Command {ip pim keep-alive-timer (31-60000)} {}
 100 Modify the time out value for a S,G flow from 31-60000
 101 seconds.  31 seconds is choosen for a lower bound
 102 because some hardware platforms cannot see data flowing
 103 in better than 30 second chunks.  This comand is vrf
 104 aware, to configure for a vrf, enter the vrf submode.
 105 @end deffn
 106
 107 @deffn Command {ip pim packets (1-100)} {}
 108 When processing packets from a neighbor process the
 109 number of packets incoming at one time before moving
 110 on to the next task.  The default value is 3 packets.
 111 This command is only useful at scale when you can
 112 possibly have a large number of pim control packets
 113 flowing.  This command is vrf aware, to configure for
 114 a vrf, enter the vrf submode.
 115 @end deffn
 116
 117 @deffn Command {ip pim register-suppress-time (5-60000)} {}
 118 Modify the time that pim will register suppress a FHR
 119 will send register notifications to the kernel.  This command
 120 is vrf aware, to configure for a vrf, enter the vrf submode.
 121 @end deffn
 122
 123 @deffn Command {ip pim send-v6-secondary} {}
 124 When sending pim hello packets tell pim to send
 125 any v6 secondary addresses on the interface.  This
 126 information is used to allow pim to use v6 nexthops
 127 in it's decision for RPF lookup.  This command
 128 is vrf aware, to configure for a vrf, enter the vrf submode.
 129 @end deffn
 130
 131 @deffn Command {ip pim ssm prefix-list WORD} {}
 132 Specify a range of group addresses via a prefix-list
 133 that forces pim to never do SM over.  This command
 134 is vrf aware, to configure for a vrf, enter the vrf submode.
 135 @end deffn
 136
 137 @deffn Command {ip multicast rpf-lookup-mode WORD} {}
 138 Modify how PIM does RPF lookups in the zebra routing table.
 139 You can use these choices:
 140 @table @lookup_modes
 141 @item longer-prefix
 142 Lookup the RPF in both tables using the longer prefix as a match
 143 @item lower-distance
 144 Lookup the RPF in both tables using the lower distance as a match
 145 @item mrib-only
 146 Lookup in the Multicast RIB only
 147 @item mrib-then-urib
 148 Lookup in the Multicast RIB then the Unicast Rib, returning first found.
 149 This is the default value for lookup if this command is not entered
 150 @item urib-only
 151 Lookup in the Unicast Rib only.
 152 @end table
 153 @end deffn
 154
 155 @node PIM Interface Configuration
 156 @section PIM Interface Configuration
 157
 158 PIM interface commands allow you to configure an
 159 interface as either a Receiver or a interface
 160 that you would like to form pim neighbors on.  If the
 161 interface is in a vrf, enter the interface command with
 162 the vrf keyword at the end.
 163
 164 @deffn {PIM Interface Command] {ip pim bfd} {}
 165 Turns on BFD support for PIM for this interface.
 166 @end deffn
 167
 168 @deffn {PIM Interface Command} {ip pim drpriority (1-4294967295)} {}
 169 Set the DR Priority for the interface.  This command is useful
 170 to allow the user to influence what node becomes the DR for a
 171 lan segment.
 172 @end deffn
 173
 174 @deffn {PIM Interface Command} {ip pim hello (1-180) (1-180)} {}
 175 Set the pim hello and hold interval for a interface.
 176 @end deffn
 177
 178 @deffn {PIM Interface Command} {ip pim sm} {}
 179 Tell pim that we would like to use this interface to form
 180 pim neighbors over.  Please note we will *not* accept
 181 igmp reports over this interface with this command.
 182 @end deffn
 183
 184 @deffn {PIM Interface Command} {ip igmp} {}
 185 Tell pim to receive IGMP reports and Query on this
 186 interface.  The default version is v3.  This command
 187 is useful on the LHR.
 188 @end deffn
 189
 190 @deffn {PIM Interface Command} {ip igmp query-interval (1-1800)} {}
 191 Set the IGMP query interval that PIM will use.
 192 @end deffn
 193
 194 @deffn {PIM Interface Command} {ip igmp query-max-response-time (10-250)} {}
 195 Set the IGMP query response timeout value.  If an report is not returned
 196 in the specified time we will assume the S,G or *,G has timed out.
 197 @end deffn
 198
 199 @deffn {PIM Interface Command} {ip igmp version (2-3)} {}
 200 Set the IGMP version used on this interface.  The default value
 201 is 3.
 202 @end deffn
 203
 204 @deffn {PIM Interface Command} {ip multicat boundary oil WORD} {}
 205 Set a pim multicast boundary, based upon the WORD prefix-list.  If
 206 a pim join or IGMP report is received on this interface and the Group
 207 is denyed by the prefix-list, PIM will ignore the join or report.
 208 @end deffn
 209
 210 @node PIM Multicast RIB insertion::
 211 @section PIM Multicast RIB insertion::
 212
 213 In order to influence Multicast RPF lookup, it is possible to insert
 214 into zebra routes for the Multicast RIB.  These routes are only
 215 used for RPF lookup and will not be used by zebra for insertion
 216 into the kernel *or* for normal rib processing.  As such it is
 217 possible to create weird states with these commands.  Use with
 218 caution.  Most of the time this will not be necessary.
 219
 220 @deffn {PIM Multicast RIB insertion} {ip mroute A.B.C.D/M A.B.C.D (1-255)} {}
 221 Insert into the Multicast Rib Route A.B.C.D/M with specified nexthop.  The distance can be specified as well if desired.
 222 @end deffn
 223
 224 @deffn {PIM Multicast RIB insertion} {ip mroute A.B.C.D/M INTERFACE (1-255)} {}
 225 Insert into the Multicast Rib Route A.B.C.D/M using the specified INTERFACE.
 226 The distance can be specified as well if desired.
 227 @end deffn
 228
 229 @node Show PIM Information::
 230 @section Show PIM Information
 231
 232 All PIM show commands are vrf aware and typically allow you to insert
 233 a specified vrf command if information is desired about a specific vrf.
 234 If no vrf is specified then the default vrf is assumed.  Finally
 235 the special keyword 'all' allows you to look at all vrfs for the command.
 236 Naming a vrf 'all' will cause great confusion.
 237
 238 @deffn {Show PIM Information} {show ip multicast}
 239 Display various information about the interfaces used in this pim
 240 instance.
 241 @end deffn
 242
 243 @deffn {Show PIM Information} {show ip mroute}
 244 Display information about installed into the kernel S,G mroutes.
 245 @end deffn
 246
 247 @deffn {Show PIM Information} {show ip mroute count}
 248 Display information about installed into the kernel S,G mroutes
 249 and in addition display data about packet flow for the mroutes.
 250 @end deffn
 251
 252 @deffn {Show PIM Information} {show ip pim assert}
 253 Display information about asserts in the PIM system for S,G mroutes.
 254 @end deffn
 255
 256 @deffn {Show PIM Information} {show ip pim assert-internal}
 257 Display internal assert state for S,G mroutes
 258 @end deffn
 259
 260 @deffn {Show PIM Information} {show ip pim assert-metric}
 261 Display metric information about assert state for S,G mroutes
 262 @end deffn
 263
 264 @deffn {Show PIM Information} {show ip pim assert-winner-metric}
 265 Display winner metric for assert state for S,G mroutes
 266 @end deffn
 267
 268 @deffn {Show PIM Information} {show ip pim group-type}
 269 Display SSM group ranges
 270 @end deffn
 271
 272 @deffn {Show PIM Information} {show ip pim interface}
 273 Display information about interfaces PIM is using.
 274 @end deffn
 275
 276 @deffn {Show PIM Information} {show ip pim join}
 277 Display information about PIM joins received.
 278 @end deffn
 279
 280 @deffn {Show PIM Information} {show ip pim local-membership} {}
 281 Display information about PIM interface local-membership
 282 @end deffn
 283
 284 @deffn {Show PIM Information} {show ip pim neighbor} {}
 285 Display information about PIM neighbors
 286 @end deffn
 287
 288 @deffn {Show PIM Information} {show ip pim nexthop} {}
 289 Display information about pim nexthops that are being
 290 used
 291 @end deffn
 292
 293 @deffn {Show PIM Information} {show ip pim nexthop-lookup} {}
 294 Display information about a S,G pair and how the RPF would
 295 be choosen.  This is especially useful if there are ECMP's
 296 available from the RPF lookup.
 297 @end deffn
 298
 299 @deffn {Show PIM Information} {show ip pim rp-info} {}
 300 Display information about RP's that are configured on
 301 this router
 302 @end deffn
 303
 304 @deffn {Show PIM Information} {show ip pim rpf} {}
 305 Display information about currently being used S,G's
 306 and their RPF lookup information.  Additionally display
 307 some statistics about what has been happening on the
 308 router
 309 @end deffn
 310
 311 @deffn {show PIM Information} {show ip pim secondary} {}
 312 Display information about an interface and all the
 313 secondary addresses associated with it
 314 @end deffn
 315
 316 @deffn {show PIM Information} {show ip pim state} {}
 317 Display information about known S,G's and incoming
 318 interface as well as the OIL and how they were choosen
 319 @end deffn
 320
 321 @deffn {show PIM Information} {show ip pim upstream} {}
 322 Display upstream information about a S,G mroute
 323 @end deffn
 324
 325 @deffn {show PIM Information} {show ip pim upstream-join-desired} {}
 326 Display upstream information for S,G's and if we desire to
 327 join the mcast tree
 328 @end deffn
 329
 330 @deffn {show PIM Information} {show ip pim upstream-rpf} {}
 331 Display upstream information for S,G's and the RPF data
 332 associated with them
 333 @end deffn
 334
 335 @deffn {show PIM Information} {show ip rpf} {}
 336 Display the multicast RIB created in zebra
 337 @end deffn
 338
 339 @node  PIM Debug Commands
 340 @section PIM Debug Commands
 341
 342 The debugging subsystem for PIM behaves in accordance with how FRR handles debugging.  You can specify debugging at the enable cli mode as well as the configure cli mode.  If you specify debug commands in the configuration cli mode, the debug commands can be persistent across restarts of the FRR pimd if the config was written out.
 343
 344 @deffn {PIM Debug Commands} {debug pim events}
 345 This turns on debugging for PIM system events.  Especially timers.
 346 @end deffn
 347
 348 @deffn {PIM Debug Commands} {debug pim nht}
 349 This turns on debugging for PIM nexthop tracking.  It will display information about RPF lookups and information about when a nexthop changes.
 350 @end deffn
 351
 352 @deffn {PIM Debug Commands} {debug pim packet-dump}
 353 This turns on an extraordinary amount of data.  Each pim packet sent and received is dumped for debugging purposes.  This should be considered a developer only command
 354 @end deffn
 355
 356 @deffn {PIM Debug Commands} {debug pim packets}
 357 This turns on information about packet generation for sending and about packet handling from a received packet
 358 @end deffn
 359
 360 @deffn {PIM Debug Commands} {debug pim trace}
 361 This traces pim code and how it is running.
 362 @end deffn
 363
 364 @deffn {PIM Debug Commands} {debug pim zebra}
 365 This gathers data about events from zebra that come up through the zapi
 366 @end deffn