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