doc/user/pim.rst

   1 .. _pim:
   2
   3 ***
   4 PIM
   5 ***
   6
   7 PIM -- Protocol Independent Multicast
   8
   9 *pimd* supports pim-sm as well as igmp v2 and v3. pim is
  10 vrf aware and can work within the context of vrf's in order to
  11 do S,G mrouting.
  12
  13 .. _starting-and-stopping-pimd:
  14
  15 Starting and Stopping pimd
  16 ==========================
  17
  18 The default configuration file name of *pimd*'s is :file:`pimd.conf`. When
  19 invoked *pimd* searches directory |INSTALL_PREFIX_ETC|. If
  20 :file:`pimd.conf` is not there then next search current directory.
  21
  22 *pimd* requires zebra for proper operation. Additionally *pimd* depends on
  23 routing properly setup and working in the network that it is working on.
  24
  25 ::
  26
  27    # zebra -d
  28    # pimd -d
  29
  30
  31 Please note that *zebra* must be invoked before *pimd*.
  32
  33 To stop *pimd* please use::
  34
  35    kill `cat /var/run/pimd.pid`
  36
  37 Certain signals have special meanings to *pimd*.
  38
  39 +---------+---------------------------------------------------------------------+
  40 | Signal  | Meaning                                                             |
  41 +=========+=====================================================================+
  42 | SIGUSR1 | Rotate the *pimd* logfile                                           |
  43 +---------+---------------------------------------------------------------------+
  44 | SIGINT  | *pimd* sweeps all installed PIM mroutes then terminates gracefully. |
  45 | SIGTERM |                                                                     |
  46 +---------+---------------------------------------------------------------------+
  47
  48 *pimd* invocation options. Common options that can be specified
  49 (:ref:`common-invocation-options`).
  50
  51 .. index:: ip pim rp A.B.C.D A.B.C.D/M
  52 .. clicmd:: ip pim rp A.B.C.D A.B.C.D/M
  53
  54    In order to use pim, it is necessary to configure a RP for join messages to
  55    be sent to. Currently the only methodology to do this is via static rp
  56    commands. All routers in the pim network must agree on these values. The
  57    first ip address is the RP's address and the second value is the matching
  58    prefix of group ranges covered. This command is vrf aware, to configure for
  59    a vrf, enter the vrf submode.
  60
  61 .. index:: ip pim spt-switchover infinity-and-beyond
  62 .. clicmd:: ip pim spt-switchover infinity-and-beyond
  63
  64    On the last hop router if it is desired to not switch over to the SPT tree.
  65    Configure this command. This command is vrf aware, to configure for a vrf,
  66    enter the vrf submode.
  67
  68 .. index:: ip pim ecmp
  69 .. clicmd:: ip pim ecmp
  70
  71    If pim has the a choice of ECMP nexthops for a particular RPF, pim will
  72    cause S,G flows to be spread out amongst the nexthops. If this command is
  73    not specified then the first nexthop found will be used. This command is vrf
  74    aware, to configure for a vrf, enter the vrf submode.
  75
  76 .. index:: ip pim ecmp rebalance
  77 .. clicmd:: ip pim ecmp rebalance
  78
  79    If pim is using ECMP and an interface goes down, cause pim to rebalance all
  80    S,G flows across the remaining nexthops. If this command is not configured
  81    pim only modifies those S,G flows that were using the interface that went
  82    down. This command is vrf aware, to configure for a vrf, enter the vrf
  83    submode.
  84
  85 .. index:: ip pim join-prune-interval (60-600)
  86 .. clicmd:: ip pim join-prune-interval (60-600)
  87
  88    Modify the join/prune interval that pim uses to the new value. Time is
  89    specified in seconds. This command is vrf aware, to configure for a vrf,
  90    enter the vrf submode.
  91
  92 .. index:: ip pim keep-alive-timer (31-60000)
  93 .. clicmd:: ip pim keep-alive-timer (31-60000)
  94
  95    Modify the time out value for a S,G flow from 31-60000 seconds. 31 seconds
  96    is chosen for a lower bound because some hardware platforms cannot see data
  97    flowing in better than 30 second chunks. This command is vrf aware, to
  98    configure for a vrf, enter the vrf submode.
  99
 100 .. index:: ip pim packets (1-100)
 101 .. clicmd:: ip pim packets (1-100)
 102
 103    When processing packets from a neighbor process the number of packets
 104    incoming at one time before moving on to the next task. The default value is
 105    3 packets.  This command is only useful at scale when you can possibly have
 106    a large number of pim control packets flowing. This command is vrf aware, to
 107    configure for a vrf, enter the vrf submode.
 108
 109 .. index:: ip pim register-suppress-time (5-60000)
 110 .. clicmd:: ip pim register-suppress-time (5-60000)
 111
 112    Modify the time that pim will register suppress a FHR will send register
 113    notifications to the kernel. This command is vrf aware, to configure for a
 114    vrf, enter the vrf submode.
 115
 116 .. index:: ip pim send-v6-secondary
 117 .. clicmd:: ip pim send-v6-secondary
 118
 119    When sending pim hello packets tell pim to send any v6 secondary addresses
 120    on the interface. This information is used to allow pim to use v6 nexthops
 121    in it's decision for RPF lookup. This command is vrf aware, to configure for
 122    a vrf, enter the vrf submode.
 123
 124 .. index:: ip pim ssm prefix-list WORD
 125 .. clicmd:: ip pim ssm prefix-list WORD
 126
 127    Specify a range of group addresses via a prefix-list that forces pim to
 128    never do SM over. This command is vrf aware, to configure for a vrf, enter
 129    the vrf submode.
 130
 131 .. index:: ip multicast rpf-lookup-mode WORD
 132 .. clicmd:: ip multicast rpf-lookup-mode WORD
 133
 134    Modify how PIM does RPF lookups in the zebra routing table.  You can use
 135    these choices:
 136
 137    longer-prefix
 138       Lookup the RPF in both tables using the longer prefix as a match
 139
 140    lower-distance
 141       Lookup the RPF in both tables using the lower distance as a match
 142
 143    mrib-only
 144       Lookup in the Multicast RIB only
 145
 146    mrib-then-urib
 147       Lookup in the Multicast RIB then the Unicast Rib, returning first found.
 148       This is the default value for lookup if this command is not entered
 149
 150    urib-only
 151       Lookup in the Unicast Rib only.
 152
 153
 154 .. _pim-interface-configuration:
 155
 156 PIM Interface Configuration
 157 ===========================
 158
 159 PIM interface commands allow you to configure an interface as either a Receiver
 160 or a interface that you would like to form pim neighbors on. If the interface
 161 is in a vrf, enter the interface command with the vrf keyword at the end.
 162
 163 .. index:: ip pim bfd
 164 .. clicmd:: ip pim bfd
 165
 166    Turns on BFD support for PIM for this interface.
 167
 168 .. index:: ip pim drpriority (1-4294967295)
 169 .. clicmd:: ip pim drpriority (1-4294967295)
 170
 171    Set the DR Priority for the interface. This command is useful to allow the
 172    user to influence what node becomes the DR for a lan segment.
 173
 174 .. index:: ip pim hello (1-180) (1-180)
 175 .. clicmd:: ip pim hello (1-180) (1-180)
 176
 177    Set the pim hello and hold interval for a interface.
 178
 179 .. index:: ip pim sm
 180 .. clicmd:: ip pim sm
 181
 182    Tell pim that we would like to use this interface to form pim neighbors
 183    over. Please note we will *not* accept igmp reports over this interface with
 184    this command.
 185
 186 .. index:: ip igmp
 187 .. clicmd:: ip igmp
 188
 189    Tell pim to receive IGMP reports and Query on this interface. The default
 190    version is v3. This command is useful on the LHR.
 191
 192 .. index:: ip igmp join A.B.C.D A.B.C.D
 193 .. clicmd:: ip igmp join A.B.C.D A.B.C.D
 194
 195    Join multicast source-group on an interface.
 196
 197 .. index:: ip igmp query-interval (1-1800)
 198 .. clicmd:: ip igmp query-interval (1-1800)
 199
 200    Set the IGMP query interval that PIM will use.
 201
 202 .. index:: ip igmp query-max-response-time (10-250)
 203 .. clicmd:: ip igmp query-max-response-time (10-250)
 204
 205    Set the IGMP query response timeout value. If an report is not returned in
 206    the specified time we will assume the S,G or \*,G has timed out.
 207
 208 .. index:: ip igmp version (2-3)
 209 .. clicmd:: ip igmp version (2-3)
 210
 211    Set the IGMP version used on this interface. The default value is 3.
 212
 213 .. index:: ip multicat boundary oil WORD
 214 .. clicmd:: ip multicat boundary oil WORD
 215
 216    Set a pim multicast boundary, based upon the WORD prefix-list. If a pim join
 217    or IGMP report is received on this interface and the Group is denied by the
 218    prefix-list, PIM will ignore the join or report.
 219
 220 .. _pim-multicast-rib-insertion:
 221
 222 PIM Multicast RIB insertion:
 223 ============================
 224
 225 In order to influence Multicast RPF lookup, it is possible to insert
 226 into zebra routes for the Multicast RIB. These routes are only
 227 used for RPF lookup and will not be used by zebra for insertion
 228 into the kernel *or* for normal rib processing. As such it is
 229 possible to create weird states with these commands. Use with
 230 caution. Most of the time this will not be necessary.
 231
 232 .. index:: ip mroute A.B.C.D/M A.B.C.D (1-255)
 233 .. clicmd:: ip mroute A.B.C.D/M A.B.C.D (1-255)
 234
 235    Insert into the Multicast Rib Route A.B.C.D/M with specified nexthop. The
 236    distance can be specified as well if desired.
 237
 238 .. index:: ip mroute A.B.C.D/M INTERFACE (1-255)
 239 .. clicmd:: ip mroute A.B.C.D/M INTERFACE (1-255)
 240
 241    Insert into the Multicast Rib Route A.B.C.D/M using the specified INTERFACE.
 242    The distance can be specified as well if desired.
 243
 244 .. _show-pim-information:
 245
 246 Show PIM Information
 247 ====================
 248
 249 All PIM show commands are vrf aware and typically allow you to insert a
 250 specified vrf command if information is desired about a specific vrf. If no
 251 vrf is specified then the default vrf is assumed. Finally the special keyword
 252 'all' allows you to look at all vrfs for the command. Naming a vrf 'all' will
 253 cause great confusion.
 254
 255 .. index:: show ip igmp interface
 256 .. clicmd:: show ip igmp interface
 257
 258    Display IGMP interface information.
 259
 260 .. index:: show ip igmp join
 261 .. clicmd:: show ip igmp join
 262
 263    Display IGMP static join information.
 264
 265 .. index:: show ip igmp groups
 266 .. clicmd:: show ip igmp groups
 267
 268    Display IGMP groups information.
 269
 270 .. index:: show ip igmp groups retransmissions
 271 .. clicmd:: show ip igmp groups retransmissions
 272
 273    Display IGMP group retransmission information.
 274
 275 .. index:: show ip igmp sources
 276 .. clicmd:: show ip igmp sources
 277
 278    Display IGMP sources information.
 279
 280 .. index:: show ip igmp sources retransmissions
 281 .. clicmd:: show ip igmp sources retransmissions
 282
 283    Display IGMP source retransmission information.
 284
 285 .. index:: show ip igmp statistics
 286 .. clicmd:: show ip igmp statistics
 287
 288    Display IGMP statistics information.
 289
 290 .. index:: show ip multicast
 291 .. clicmd:: show ip multicast
 292
 293    Display various information about the interfaces used in this pim instance.
 294
 295 .. index:: show ip mroute
 296 .. clicmd:: show ip mroute
 297
 298    Display information about installed into the kernel S,G mroutes.
 299
 300 .. index:: show ip mroute count
 301 .. clicmd:: show ip mroute count
 302
 303    Display information about installed into the kernel S,G mroutes and in
 304    addition display data about packet flow for the mroutes.
 305
 306 .. index:: show ip pim assert
 307 .. clicmd:: show ip pim assert
 308
 309    Display information about asserts in the PIM system for S,G mroutes.
 310
 311 .. index:: show ip pim assert-internal
 312 .. clicmd:: show ip pim assert-internal
 313
 314    Display internal assert state for S,G mroutes
 315
 316 .. index:: show ip pim assert-metric
 317 .. clicmd:: show ip pim assert-metric
 318
 319    Display metric information about assert state for S,G mroutes
 320
 321 .. index:: show ip pim assert-winner-metric
 322 .. clicmd:: show ip pim assert-winner-metric
 323
 324    Display winner metric for assert state for S,G mroutes
 325
 326 .. index:: show ip pim group-type
 327 .. clicmd:: show ip pim group-type
 328
 329    Display SSM group ranges.
 330
 331 .. index:: show ip pim interface
 332 .. clicmd:: show ip pim interface
 333
 334    Display information about interfaces PIM is using.
 335
 336 .. index:: show ip pim join
 337 .. clicmd:: show ip pim join
 338
 339    Display information about PIM joins received.
 340
 341 .. index:: show ip pim local-membership
 342 .. clicmd:: show ip pim local-membership
 343
 344    Display information about PIM interface local-membership.
 345
 346 .. index:: show ip pim neighbor
 347 .. clicmd:: show ip pim neighbor
 348
 349    Display information about PIM neighbors.
 350
 351 .. index:: show ip pim nexthop
 352 .. clicmd:: show ip pim nexthop
 353
 354    Display information about pim nexthops that are being used.
 355
 356 .. index:: show ip pim nexthop-lookup
 357 .. clicmd:: show ip pim nexthop-lookup
 358
 359    Display information about a S,G pair and how the RPF would be chosen. This
 360    is especially useful if there are ECMP's available from the RPF lookup.
 361
 362 .. index:: show ip pim rp-info
 363 .. clicmd:: show ip pim rp-info
 364
 365    Display information about RP's that are configured on this router.
 366
 367 .. index:: show ip pim rpf
 368 .. clicmd:: show ip pim rpf
 369
 370    Display information about currently being used S,G's and their RPF lookup
 371    information. Additionally display some statistics about what has been
 372    happening on the router.
 373
 374 .. index:: show ip pim secondary
 375 .. clicmd:: show ip pim secondary
 376
 377    Display information about an interface and all the secondary addresses
 378    associated with it.
 379
 380 .. index:: show ip pim state
 381 .. clicmd:: show ip pim state
 382
 383    Display information about known S,G's and incoming interface as well as the
 384    OIL and how they were chosen.
 385
 386 .. index:: show ip pim upstream
 387 .. clicmd:: show ip pim upstream
 388
 389    Display upstream information about a S,G mroute.
 390
 391 .. index:: show ip pim upstream-join-desired
 392 .. clicmd:: show ip pim upstream-join-desired
 393
 394    Display upstream information for S,G's and if we desire to
 395    join the multicast tree
 396
 397 .. index:: show ip pim upstream-rpf
 398 .. clicmd:: show ip pim upstream-rpf
 399
 400    Display upstream information for S,G's and the RPF data associated with them.
 401
 402 .. index:: show ip rpf
 403 .. clicmd:: show ip rpf
 404
 405    Display the multicast RIB created in zebra.
 406
 407 .. index:: mtrace A.B.C.D [A.B.C.D]
 408 .. clicmd:: mtrace A.B.C.D [A.B.C.D]
 409
 410    Display multicast traceroute towards source, optionally for particular group.
 411
 412 PIM Debug Commands
 413 ==================
 414
 415 The debugging subsystem for PIM behaves in accordance with how FRR handles
 416 debugging. You can specify debugging at the enable CLI mode as well as the
 417 configure CLI mode. If you specify debug commands in the configuration cli
 418 mode, the debug commands can be persistent across restarts of the FRR pimd if
 419 the config was written out.
 420
 421 .. index:: debug igmp
 422 .. clicmd:: debug igmp
 423
 424    This turns on debugging for IGMP protocol activity.
 425
 426 .. index:: debug mtrace
 427 .. clicmd:: debug mtrace
 428
 429    This turns on debugging for mtrace protocol activity.
 430
 431 .. index:: debug mroute
 432 .. clicmd:: debug mroute
 433
 434    This turns on debugging for PIM interaction with kernel MFC cache.
 435
 436 .. index:: debug pim events
 437 .. clicmd:: debug pim events
 438
 439    This turns on debugging for PIM system events. Especially timers.
 440
 441 .. index:: debug pim nht
 442 .. clicmd:: debug pim nht
 443
 444    This turns on debugging for PIM nexthop tracking. It will display
 445    information about RPF lookups and information about when a nexthop changes.
 446
 447 .. index:: debug pim packet-dump
 448 .. clicmd:: debug pim packet-dump
 449
 450    This turns on an extraordinary amount of data. Each pim packet sent and
 451    received is dumped for debugging purposes. This should be considered a
 452    developer only command.
 453
 454 .. index:: debug pim packets
 455 .. clicmd:: debug pim packets
 456
 457    This turns on information about packet generation for sending and about
 458    packet handling from a received packet.
 459
 460 .. index:: debug pim trace
 461 .. clicmd:: debug pim trace
 462
 463    This traces pim code and how it is running.
 464
 465 .. index:: debug pim zebra
 466 .. clicmd:: debug pim zebra
 467
 468    This gathers data about events from zebra that come up through the ZAPI.
 469
 470 PIM Clear Commands
 471 ==================
 472 Clear commands reset various variables.
 473
 474 .. index:: clear ip interfaces
 475 .. clicmd:: clear ip interfaces
 476
 477    Reset interfaces.
 478
 479 .. index:: clear ip igmp interfaces
 480 .. clicmd:: clear ip igmp interfaces
 481
 482    Reset IGMP interfaces.
 483
 484 .. index:: clear ip mroute
 485 .. clicmd:: clear ip mroute
 486
 487    Reset multicast routes.
 488
 489 .. index:: clear ip pim interfaces
 490 .. clicmd:: clear ip pim interfaces
 491
 492    Reset PIM interfaces.
 493
 494 .. index:: clear ip pim oil
 495 .. clicmd:: clear ip pim oil
 496
 497    Rescan PIM OIL (output interface list).