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 query-interval (1-1800)
 193 .. clicmd:: ip igmp query-interval (1-1800)
 194
 195    Set the IGMP query interval that PIM will use.
 196
 197 .. index:: ip igmp query-max-response-time (10-250)
 198 .. clicmd:: ip igmp query-max-response-time (10-250)
 199
 200    Set the IGMP query response timeout value. If an report is not returned in
 201    the specified time we will assume the S,G or \*,G has timed out.
 202
 203 .. index:: ip igmp version (2-3)
 204 .. clicmd:: ip igmp version (2-3)
 205
 206    Set the IGMP version used on this interface. The default value is 3.
 207
 208 .. index:: ip multicat boundary oil WORD
 209 .. clicmd:: ip multicat boundary oil WORD
 210
 211    Set a pim multicast boundary, based upon the WORD prefix-list. If a pim join
 212    or IGMP report is received on this interface and the Group is denied by the
 213    prefix-list, PIM will ignore the join or report.
 214
 215 .. _pim-multicast-rib-insertion:
 216
 217 PIM Multicast RIB insertion:
 218 ============================
 219
 220 In order to influence Multicast RPF lookup, it is possible to insert
 221 into zebra routes for the Multicast RIB. These routes are only
 222 used for RPF lookup and will not be used by zebra for insertion
 223 into the kernel *or* for normal rib processing. As such it is
 224 possible to create weird states with these commands. Use with
 225 caution. Most of the time this will not be necessary.
 226
 227 .. index:: ip mroute A.B.C.D/M A.B.C.D (1-255)
 228 .. clicmd:: ip mroute A.B.C.D/M A.B.C.D (1-255)
 229
 230    Insert into the Multicast Rib Route A.B.C.D/M with specified nexthop. The
 231    distance can be specified as well if desired.
 232
 233 .. index:: ip mroute A.B.C.D/M INTERFACE (1-255)
 234 .. clicmd:: ip mroute A.B.C.D/M INTERFACE (1-255)
 235
 236    Insert into the Multicast Rib Route A.B.C.D/M using the specified INTERFACE.
 237    The distance can be specified as well if desired.
 238
 239 .. _show-pim-information:
 240
 241 Show PIM Information
 242 ====================
 243
 244 All PIM show commands are vrf aware and typically allow you to insert a
 245 specified vrf command if information is desired about a specific vrf. If no
 246 vrf is specified then the default vrf is assumed. Finally the special keyword
 247 'all' allows you to look at all vrfs for the command. Naming a vrf 'all' will
 248 cause great confusion.
 249
 250 .. index:: show ip multicast
 251 .. clicmd:: show ip multicast
 252
 253    Display various information about the interfaces used in this pim instance.
 254
 255 .. index:: show ip mroute
 256 .. clicmd:: show ip mroute
 257
 258    Display information about installed into the kernel S,G mroutes.
 259
 260 .. index:: show ip mroute count
 261 .. clicmd:: show ip mroute count
 262
 263    Display information about installed into the kernel S,G mroutes and in
 264    addition display data about packet flow for the mroutes.
 265
 266 .. index:: show ip pim assert
 267 .. clicmd:: show ip pim assert
 268
 269    Display information about asserts in the PIM system for S,G mroutes.
 270
 271 .. index:: show ip pim assert-internal
 272 .. clicmd:: show ip pim assert-internal
 273
 274    Display internal assert state for S,G mroutes
 275
 276 .. index:: show ip pim assert-metric
 277 .. clicmd:: show ip pim assert-metric
 278
 279    Display metric information about assert state for S,G mroutes
 280
 281 .. index:: show ip pim assert-winner-metric
 282 .. clicmd:: show ip pim assert-winner-metric
 283
 284    Display winner metric for assert state for S,G mroutes
 285
 286 .. index:: show ip pim group-type
 287 .. clicmd:: show ip pim group-type
 288
 289    Display SSM group ranges.
 290
 291 .. index:: show ip pim interface
 292 .. clicmd:: show ip pim interface
 293
 294    Display information about interfaces PIM is using.
 295
 296 .. index:: show ip pim join
 297 .. clicmd:: show ip pim join
 298
 299    Display information about PIM joins received.
 300
 301 .. index:: show ip pim local-membership
 302 .. clicmd:: show ip pim local-membership
 303
 304    Display information about PIM interface local-membership.
 305
 306 .. index:: show ip pim neighbor
 307 .. clicmd:: show ip pim neighbor
 308
 309    Display information about PIM neighbors.
 310
 311 .. index:: show ip pim nexthop
 312 .. clicmd:: show ip pim nexthop
 313
 314    Display information about pim nexthops that are being used.
 315
 316 .. index:: show ip pim nexthop-lookup
 317 .. clicmd:: show ip pim nexthop-lookup
 318
 319    Display information about a S,G pair and how the RPF would be chosen. This
 320    is especially useful if there are ECMP's available from the RPF lookup.
 321
 322 .. index:: show ip pim rp-info
 323 .. clicmd:: show ip pim rp-info
 324
 325    Display information about RP's that are configured on this router.
 326
 327 .. index:: show ip pim rpf
 328 .. clicmd:: show ip pim rpf
 329
 330    Display information about currently being used S,G's and their RPF lookup
 331    information. Additionally display some statistics about what has been
 332    happening on the router.
 333
 334 .. index:: show ip pim secondary
 335 .. clicmd:: show ip pim secondary
 336
 337    Display information about an interface and all the secondary addresses
 338    associated with it.
 339
 340 .. index:: show ip pim state
 341 .. clicmd:: show ip pim state
 342
 343    Display information about known S,G's and incoming interface as well as the
 344    OIL and how they were chosen.
 345
 346 .. index:: show ip pim upstream
 347 .. clicmd:: show ip pim upstream
 348
 349    Display upstream information about a S,G mroute.
 350
 351 .. index:: show ip pim upstream-join-desired
 352 .. clicmd:: show ip pim upstream-join-desired
 353
 354    Display upstream information for S,G's and if we desire to
 355    join the multicast tree
 356
 357 .. index:: show ip pim upstream-rpf
 358 .. clicmd:: show ip pim upstream-rpf
 359
 360    Display upstream information for S,G's and the RPF data associated with them.
 361
 362 .. index:: show ip rpf
 363 .. clicmd:: show ip rpf
 364
 365    Display the multicast RIB created in zebra.
 366
 367 PIM Debug Commands
 368 ==================
 369
 370 The debugging subsystem for PIM behaves in accordance with how FRR handles
 371 debugging. You can specify debugging at the enable CLI mode as well as the
 372 configure CLI mode. If you specify debug commands in the configuration cli
 373 mode, the debug commands can be persistent across restarts of the FRR pimd if
 374 the config was written out.
 375
 376 .. index:: debug pim events
 377 .. clicmd:: debug pim events
 378
 379    This turns on debugging for PIM system events. Especially timers.
 380
 381 .. index:: debug pim nht
 382 .. clicmd:: debug pim nht
 383
 384    This turns on debugging for PIM nexthop tracking. It will display
 385    information about RPF lookups and information about when a nexthop changes.
 386
 387 .. index:: debug pim packet-dump
 388 .. clicmd:: debug pim packet-dump
 389
 390    This turns on an extraordinary amount of data. Each pim packet sent and
 391    received is dumped for debugging purposes. This should be considered a
 392    developer only command.
 393
 394 .. index:: debug pim packets
 395 .. clicmd:: debug pim packets
 396
 397    This turns on information about packet generation for sending and about
 398    packet handling from a received packet.
 399
 400 .. index:: debug pim trace
 401 .. clicmd:: debug pim trace
 402
 403    This traces pim code and how it is running.
 404
 405 .. index:: debug pim zebra
 406 .. clicmd:: debug pim zebra
 407
 408    This gathers data about events from zebra that come up through the ZAPI.