7 PIM -- Protocol Independent Multicast
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.
16 On Linux for PIM-SM operation you *must* have kernel version 4.19 or greater.
17 To use PIM for EVPN BUM forwarding, kernels 5.0 or greater are required.
18 OpenBSD has no multicast support and FreeBSD, and NetBSD only
21 .. _starting-and-stopping-pimd:
23 Starting and Stopping pimd
24 ==========================
26 The default configuration file name of *pimd*'s is :file:`pimd.conf`. When
27 invoked *pimd* searches directory |INSTALL_PREFIX_ETC|. If
28 :file:`pimd.conf` is not there then next search current directory.
30 *pimd* requires zebra for proper operation. Additionally *pimd* depends on
31 routing properly setup and working in the network that it is working on.
39 Please note that *zebra* must be invoked before *pimd*.
41 To stop *pimd* please use::
43 kill `cat /var/run/pimd.pid`
45 Certain signals have special meanings to *pimd*.
47 +---------+---------------------------------------------------------------------+
49 +=========+=====================================================================+
50 | SIGUSR1 | Rotate the *pimd* logfile |
51 +---------+---------------------------------------------------------------------+
52 | SIGINT | *pimd* sweeps all installed PIM mroutes then terminates gracefully. |
54 +---------+---------------------------------------------------------------------+
56 *pimd* invocation options. Common options that can be specified
57 (:ref:`common-invocation-options`).
59 .. clicmd:: 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 messages to
62 be sent to. Currently the only methodology to do this is via static rp
63 commands. All routers in the pim network must agree on these values. The
64 first ip address is the RP's address and the second value is the matching
65 prefix of group ranges covered. This command is vrf aware, to configure for
66 a vrf, enter the vrf submode.
68 .. clicmd:: ip pim rp keep-alive-timer (1-65535)
70 Modify the time out value for a S,G flow from 1-65535 seconds at RP.
71 The normal keepalive period for the KAT(S,G) defaults to 210 seconds.
72 However, at the RP, the keepalive period must be at least the
73 Register_Suppression_Time, or the RP may time out the (S,G) state
74 before the next Null-Register arrives. Thus, the KAT(S,G) is set to
75 max(Keepalive_Period, RP_Keepalive_Period) when a Register-Stop is sent.
76 If choosing a value below 31 seconds be aware that some hardware platforms
77 cannot see data flowing in better than 30 second chunks. This command is
78 vrf aware, to configure for a vrf, enter the vrf submode.
80 .. clicmd:: ip pim register-accept-list PLIST
82 When pim receives a register packet the source of the packet will be compared
83 to the prefix-list specified, PLIST, and if a permit is received normal
84 processing continues. If a deny is returned for the source address of the
85 register packet a register stop message is sent to the source.
87 .. clicmd:: ip pim spt-switchover infinity-and-beyond [prefix-list PLIST]
89 On the last hop router if it is desired to not switch over to the SPT tree
90 configure this command. Optional parameter prefix-list can be use to control
91 which groups to switch or not switch. If a group is PERMIT as per the
92 PLIST, then the SPT switchover does not happen for it and if it is DENY,
93 then the SPT switchover happens.
94 This command is vrf aware, to configure for a vrf,
95 enter the vrf submode.
97 .. clicmd:: ip pim ecmp
99 If pim has the a choice of ECMP nexthops for a particular RPF, pim will
100 cause S,G flows to be spread out amongst the nexthops. If this command is
101 not specified then the first nexthop found will be used. This command is vrf
102 aware, to configure for a vrf, enter the vrf submode.
104 .. clicmd:: ip pim ecmp rebalance
106 If pim is using ECMP and an interface goes down, cause pim to rebalance all
107 S,G flows across the remaining nexthops. If this command is not configured
108 pim only modifies those S,G flows that were using the interface that went
109 down. This command is vrf aware, to configure for a vrf, enter the vrf
112 .. clicmd:: ip pim join-prune-interval (1-65535)
114 Modify the join/prune interval that pim uses to the new value. Time is
115 specified in seconds. This command is vrf aware, to configure for a vrf,
116 enter the vrf submode. The default time is 60 seconds. If you enter
117 a value smaller than 60 seconds be aware that this can and will affect
118 convergence at scale.
120 .. clicmd:: ip pim keep-alive-timer (1-65535)
122 Modify the time out value for a S,G flow from 1-65535 seconds. If choosing
123 a value below 31 seconds be aware that some hardware platforms cannot see data
124 flowing in better than 30 second chunks. This command is vrf aware, to
125 configure for a vrf, enter the vrf submode.
127 .. clicmd:: ip pim packets (1-255)
129 When processing packets from a neighbor process the number of packets
130 incoming at one time before moving on to the next task. The default value is
131 3 packets. This command is only useful at scale when you can possibly have
132 a large number of pim control packets flowing. This command is vrf aware, to
133 configure for a vrf, enter the vrf submode.
135 .. clicmd:: ip pim register-suppress-time (1-65535)
137 Modify the time that pim will register suppress a FHR will send register
138 notifications to the kernel. This command is vrf aware, to configure for a
139 vrf, enter the vrf submode.
141 .. clicmd:: ip pim send-v6-secondary
143 When sending pim hello packets tell pim to send any v6 secondary addresses
144 on the interface. This information is used to allow pim to use v6 nexthops
145 in it's decision for RPF lookup. This command is vrf aware, to configure for
146 a vrf, enter the vrf submode.
148 .. clicmd:: ip pim ssm prefix-list WORD
150 Specify a range of group addresses via a prefix-list that forces pim to
151 never do SM over. This command is vrf aware, to configure for a vrf, enter
154 .. clicmd:: ip multicast rpf-lookup-mode WORD
156 Modify how PIM does RPF lookups in the zebra routing table. You can use
160 Lookup the RPF in both tables using the longer prefix as a match
163 Lookup the RPF in both tables using the lower distance as a match
166 Lookup in the Multicast RIB only
169 Lookup in the Multicast RIB then the Unicast Rib, returning first found.
170 This is the default value for lookup if this command is not entered
173 Lookup in the Unicast Rib only.
175 .. clicmd:: ip igmp generate-query-once [version (2-3)]
177 Generate IGMP query (v2/v3) on user requirement. This will not depend on
178 the existing IGMP general query timer.If no version is provided in the cli,
179 the default will be the igmp version enabled on that interface.
181 .. clicmd:: ip igmp watermark-warn (1-65535)
183 Configure watermark warning generation for an igmp group limit. Generates
184 warning once the configured group limit is reached while adding new groups.
185 'no' form of the command disables the warning generation. This command is
186 vrf aware. To configure per vrf, enter vrf submode.
188 .. _pim-interface-configuration:
190 PIM Interface Configuration
191 ===========================
193 PIM interface commands allow you to configure an interface as either a Receiver
194 or a interface that you would like to form pim neighbors on. If the interface
195 is in a vrf, enter the interface command with the vrf keyword at the end.
197 .. clicmd:: ip pim active-active
199 Turn on pim active-active configuration for a Vxlan interface. This
200 command will not do anything if you do not have the underlying ability
201 of a mlag implementation.
203 .. clicmd:: ip pim bsm
205 Tell pim that we would like to use this interface to process bootstrap
206 messages. This is enabled by default. 'no' form of this command is used to
207 restrict bsm messages on this interface.
209 .. clicmd:: ip pim unicast-bsm
211 Tell pim that we would like to allow interface to process unicast bootstrap
212 messages. This is enabled by default. 'no' form of this command is used to
213 restrict processing of unicast bsm messages on this interface.
215 .. clicmd:: ip pim drpriority (1-4294967295)
217 Set the DR Priority for the interface. This command is useful to allow the
218 user to influence what node becomes the DR for a lan segment.
220 .. clicmd:: ip pim hello (1-65535) (1-65535)
222 Set the pim hello and hold interval for a interface.
226 Tell pim that we would like to use this interface to form pim neighbors
227 over. Please note that this command does not enable the reception of IGMP
228 reports on the interface. Refer to the next `ip igmp` command for IGMP
231 .. clicmd:: ip pim use-source A.B.C.D
233 If you have multiple addresses configured on a particular interface
234 and would like pim to use a specific source address associated with
237 .. clicmd:: ip pim passive
239 Disable sending and receiving pim control packets on the interface.
243 Tell pim to receive IGMP reports and Query on this interface. The default
244 version is v3. This command is useful on a LHR.
246 .. clicmd:: ip igmp join A.B.C.D [A.B.C.D]
248 Join multicast group or source-group on an interface.
250 .. clicmd:: ip igmp query-interval (1-65535)
252 Set the IGMP query interval that PIM will use.
254 .. clicmd:: ip igmp query-max-response-time (1-65535)
256 Set the IGMP query response timeout value. If an report is not returned in
257 the specified time we will assume the S,G or \*,G has timed out.
259 .. clicmd:: ip igmp version (2-3)
261 Set the IGMP version used on this interface. The default value is 3.
263 .. clicmd:: ip multicast boundary oil WORD
265 Set a pim multicast boundary, based upon the WORD prefix-list. If a pim join
266 or IGMP report is received on this interface and the Group is denied by the
267 prefix-list, PIM will ignore the join or report.
269 .. clicmd:: ip igmp last-member-query-count (1-255)
271 Set the IGMP last member query count. The default value is 2. 'no' form of
272 this command is used to to configure back to the default value.
274 .. clicmd:: ip igmp last-member-query-interval (1-65535)
276 Set the IGMP last member query interval in deciseconds. The default value is
277 10 deciseconds. 'no' form of this command is used to to configure back to the
280 .. clicmd:: ip mroute INTERFACE A.B.C.D [A.B.C.D]
282 Set a static multicast route for a traffic coming on the current interface to
283 be forwarded on the given interface if the traffic matches the group address
284 and optionally the source address.
289 :ref:`bfd-pim-peer-config`
292 .. _pim-multicast-rib:
297 In order to influence Multicast RPF lookup, it is possible to insert
298 into zebra routes for the Multicast RIB. These routes are only
299 used for RPF lookup and will not be used by zebra for insertion
300 into the kernel *or* for normal rib processing. As such it is
301 possible to create weird states with these commands. Use with
302 caution. Most of the time this will not be necessary.
304 .. clicmd:: ip mroute A.B.C.D/M A.B.C.D (1-255)
306 Insert into the Multicast Rib Route A.B.C.D/M with specified nexthop. The
307 distance can be specified as well if desired.
309 .. clicmd:: ip mroute A.B.C.D/M INTERFACE (1-255)
311 Insert into the Multicast Rib Route A.B.C.D/M using the specified INTERFACE.
312 The distance can be specified as well if desired.
314 .. _msdp-configuration:
316 Multicast Source Discovery Protocol (MSDP) Configuration
317 ========================================================
319 MSDP can be setup in different ways:
321 * MSDP meshed-group: where all peers are connected with each other creating
322 a fully meshed network. SAs (source active) messages are not forwarded in
323 this mode because the origin is able to send SAs to all members.
325 This setup is commonly used with anycast.
327 * MSDP peering: when there is one or more peers that are not fully meshed. SAs
328 may be forwarded depending on the result of filtering and RPF checks.
330 This setup is commonly consistent with BGP peerings (for RPF checks).
332 * MSDP default peer: there is only one peer and all SAs will be forwarded
337 MSDP default peer and SA filtering is not implemented.
340 Commands available for MSDP:
342 .. clicmd:: ip msdp timers (1-65535) (1-65535) [(1-65535)]
344 Configure global MSDP timers.
346 First value is the keep-alive interval. This configures the interval in
347 seconds between keep-alive messages. The default value is 60 seconds. It
348 should be less than the remote hold time.
350 Second value is the hold-time. This configures the interval in seconds before
351 closing a non responding connection. The default value is 75. This value
352 should be greater than the remote keep alive time.
354 Third value is the connection retry interval and it is optional. This
355 configures the interval between connection attempts. The default value
358 .. clicmd:: ip msdp mesh-group WORD member A.B.C.D
360 Create or update a mesh group to include the specified MSDP peer.
362 .. clicmd:: ip msdp mesh-group WORD source A.B.C.D
364 Create or update a mesh group to set the source address used to connect to
367 .. clicmd:: ip msdp peer A.B.C.D source A.B.C.D
369 Create a regular MSDP session with peer using the specified source address.
372 .. _show-pim-information:
377 All PIM show commands are vrf aware and typically allow you to insert a
378 specified vrf command if information is desired about a specific vrf. If no
379 vrf is specified then the default vrf is assumed. Finally the special keyword
380 'all' allows you to look at all vrfs for the command. Naming a vrf 'all' will
381 cause great confusion.
383 .. clicmd:: show ip igmp interface
385 Display IGMP interface information.
387 .. clicmd:: show ip igmp [vrf NAME] join [json]
389 Display IGMP static join information for a specific vrf.
390 If "vrf all" is provided, it displays information for all the vrfs present.
392 .. clicmd:: show ip igmp groups
394 Display IGMP groups information.
396 .. clicmd:: show ip igmp groups retransmissions
398 Display IGMP group retransmission information.
400 .. clicmd:: show ip igmp [vrf NAME] sources [json]
402 Display IGMP sources information.
404 .. clicmd:: show ip igmp sources retransmissions
406 Display IGMP source retransmission information.
408 .. clicmd:: show ip igmp statistics
410 Display IGMP statistics information.
412 .. clicmd:: show ip multicast
414 Display various information about the interfaces used in this pim instance.
416 .. clicmd:: show ip mroute [vrf NAME] [A.B.C.D [A.B.C.D]] [fill] [json]
418 Display information about installed into the kernel S,G mroutes. If
419 one address is specified we assume it is the Group we are interested
420 in displaying data on. If the second address is specified then it is
421 Source Group. The keyword `fill` says to fill in all assumed data
422 for test/data gathering purposes.
424 .. clicmd:: show ip mroute [vrf NAME] count [json]
426 Display information about installed into the kernel S,G mroutes and in
427 addition display data about packet flow for the mroutes for a specific
430 .. clicmd:: show ip mroute vrf all count [json]
432 Display information about installed into the kernel S,G mroutes and in
433 addition display data about packet flow for the mroutes for all vrfs.
435 .. clicmd:: show ip mroute [vrf NAME] summary [json]
437 Display total number of S,G mroutes and number of S,G mroutes installed
438 into the kernel for a specific vrf.
440 .. clicmd:: show ip mroute vrf all summary [json]
442 Display total number of S,G mroutes and number of S,G mroutes
443 installed into the kernel for all vrfs.
445 .. clicmd:: show ip msdp mesh-group
447 Display the configured mesh-groups, the local address associated with each
448 mesh-group, the peer members included in each mesh-group, and their status.
450 .. clicmd:: show ip msdp peer
452 Display information about the MSDP peers. That includes the peer address,
453 the local address used to establish the connection to the peer, the
454 connection status, and the number of active sources.
456 .. clicmd:: show ip pim assert
458 Display information about asserts in the PIM system for S,G mroutes.
459 This command does not show S,G Channel states that in a NOINFO state.
461 .. clicmd:: show ip pim assert-internal
463 Display internal assert state for S,G mroutes
465 .. clicmd:: show ip pim assert-metric
467 Display metric information about assert state for S,G mroutes
469 .. clicmd:: show ip pim assert-winner-metric
471 Display winner metric for assert state for S,G mroutes
473 .. clicmd:: show ip pim group-type
475 Display SSM group ranges.
477 .. clicmd:: show ip pim interface
479 Display information about interfaces PIM is using.
481 .. clicmd:: show ip pim mlag [vrf NAME|all] interface [detail|WORD] [json]
483 Display mlag interface information.
485 .. clicmd:: show ip pim join
487 Display information about PIM joins received. If one address is specified
488 then we assume it is the Group we are interested in displaying data on.
489 If the second address is specified then it is Source Group.
491 .. clicmd:: show ip pim local-membership
493 Display information about PIM interface local-membership.
495 .. clicmd:: show ip pim mlag summary [json]
497 Display mlag information state that PIM is keeping track of.
499 .. clicmd:: show ip pim neighbor
501 Display information about PIM neighbors.
503 .. clicmd:: show ip pim nexthop
505 Display information about pim nexthops that are being used.
507 .. clicmd:: show ip pim nexthop-lookup
509 Display information about a S,G pair and how the RPF would be chosen. This
510 is especially useful if there are ECMP's available from the RPF lookup.
512 .. clicmd:: show ip pim [vrf NAME] rp-info [A.B.C.D/M] [json]
514 Display information about RP's that are configured on this router.
516 You can filter the output by specifying an arbitrary group range.
520 # show ip pim rp-info
521 RP address group/prefix-list OIF I am RP Source Group-Type
522 192.168.10.123 225.0.0.0/24 eth2 yes Static ASM
523 192.168.10.123 239.0.0.0/8 eth2 yes Static ASM
524 192.168.10.123 239.4.0.0/24 eth2 yes Static SSM
526 # show ip pim rp-info 239.4.0.0/25
527 RP address group/prefix-list OIF I am RP Source Group-Type
528 192.168.10.123 239.0.0.0/8 eth2 yes Static ASM
529 192.168.10.123 239.4.0.0/24 eth2 yes Static SSM
531 .. clicmd:: show ip pim rpf
533 Display information about currently being used S,G's and their RPF lookup
534 information. Additionally display some statistics about what has been
535 happening on the router.
537 .. clicmd:: show ip pim secondary
539 Display information about an interface and all the secondary addresses
542 .. clicmd:: show ip pim state
544 Display information about known S,G's and incoming interface as well as the
545 OIL and how they were chosen.
547 .. clicmd:: show ip pim [vrf NAME] upstream [A.B.C.D [A.B.C.D]] [json]
549 Display upstream information about a S,G mroute. Allow the user to
550 specify sub Source and Groups that we are only interested in.
552 .. clicmd:: show ip pim upstream-join-desired
554 Display upstream information for S,G's and if we desire to
555 join the multicast tree
557 .. clicmd:: show ip pim upstream-rpf
559 Display upstream information for S,G's and the RPF data associated with them.
561 .. clicmd:: show ip pim [vrf NAME] mlag upstream [A.B.C.D [A.B.C.D]] [json]
563 Display upstream entries that are synced across MLAG switches.
564 Allow the user to specify sub Source and Groups address filters.
566 .. clicmd:: show ip pim mlag summary
568 Display PIM MLAG (multi-chassis link aggregation) session status and
569 control message statistics.
571 .. clicmd:: show ip pim bsr
573 Display current bsr, its uptime and last received bsm age.
575 .. clicmd:: show ip pim bsrp-info
577 Display group-to-rp mappings received from E-BSR.
579 .. clicmd:: show ip pim bsm-database
581 Display all fragments of stored bootstrap message in user readable format.
583 .. clicmd:: mtrace A.B.C.D [A.B.C.D]
585 Display multicast traceroute towards source, optionally for particular group.
587 .. clicmd:: show ip multicast count [vrf NAME] [json]
589 Display multicast data packets count per interface for a vrf.
591 .. clicmd:: show ip multicast count vrf all [json]
593 Display multicast data packets count per interface for all vrf.
598 :ref:`multicast-rib-commands`
604 The debugging subsystem for PIM behaves in accordance with how FRR handles
605 debugging. You can specify debugging at the enable CLI mode as well as the
606 configure CLI mode. If you specify debug commands in the configuration cli
607 mode, the debug commands can be persistent across restarts of the FRR pimd if
608 the config was written out.
610 .. clicmd:: debug igmp
612 This turns on debugging for IGMP protocol activity.
614 .. clicmd:: debug mtrace
616 This turns on debugging for mtrace protocol activity.
618 .. clicmd:: debug mroute
620 This turns on debugging for PIM interaction with kernel MFC cache.
622 .. clicmd:: debug pim events
624 This turns on debugging for PIM system events. Especially timers.
626 .. clicmd:: debug pim nht
628 This turns on debugging for PIM nexthop tracking. It will display
629 information about RPF lookups and information about when a nexthop changes.
631 .. clicmd:: debug pim nht detail
633 This turns on debugging for PIM nexthop in detail. This is not enabled
636 .. clicmd:: debug pim packet-dump
638 This turns on an extraordinary amount of data. Each pim packet sent and
639 received is dumped for debugging purposes. This should be considered a
640 developer only command.
642 .. clicmd:: debug pim packets
644 This turns on information about packet generation for sending and about
645 packet handling from a received packet.
647 .. clicmd:: debug pim trace
649 This traces pim code and how it is running.
651 .. clicmd:: debug pim bsm
653 This turns on debugging for BSR message processing.
655 .. clicmd:: debug pim zebra
657 This gathers data about events from zebra that come up through the ZAPI.
661 Clear commands reset various variables.
663 .. clicmd:: clear ip interfaces
667 .. clicmd:: clear ip igmp interfaces
669 Reset IGMP interfaces.
671 .. clicmd:: clear ip mroute
673 Reset multicast routes.
675 .. clicmd:: clear ip mroute [vrf NAME] count
677 When this command is issued, reset the counts of data shown for
678 packet count, byte count and wrong interface to 0 and start count
681 .. clicmd:: clear ip pim interfaces
683 Reset PIM interfaces.
685 .. clicmd:: clear ip pim oil
687 Rescan PIM OIL (output interface list).
689 .. clicmd:: clear ip pim [vrf NAME] bsr-data
691 This command will clear the BSM scope data struct. This command also
692 removes the next hop tracking for the bsr and resets the upstreams
693 for the dynamically learnt RPs.
695 PIM EVPN configuration
696 ======================
697 To use PIM in the underlay for overlay BUM forwarding associate a multicast
698 group with the L2 VNI. The actual configuration is based on your distribution.
699 Here is an ifupdown2 example::
705 vxlan-local-tunnelip 27.0.0.11
706 vxlan-mcastgrp 239.1.1.100
710 PIM will see the ``vxlan-mcastgrp`` configuration and auto configure state
711 to properly forward BUM traffic.
713 PIM also needs to be configured in the underlay to allow the BUM MDT to be
714 setup. This is existing PIM configuration:
716 - Enable pim on the underlay L3 interface via the "ip pim" command.
717 - Configure RPs for the BUM multicast group range.
718 - Ensure the PIM is enabled on the lo of the VTEPs and the RP.
730 ! You may want to enable ssmpingd for troubleshooting
731 ! See http://www.venaas.no/multicast/ssmping/
737 ! - Enable "ip pim ssm" on the interface directly attached to the
738 ! multicast source host (if this is the first-hop router)
739 ! - Enable "ip pim ssm" on pim-routers-facing interfaces
740 ! - Enable "ip igmp" on IGMPv3-hosts-facing interfaces
741 ! - In order to inject IGMPv3 local membership information in the
742 ! PIM protocol state, enable both "ip pim ssm" and "ip igmp" on
743 ! the same interface; otherwise PIM won't advertise
744 ! IGMPv3-learned membership to other PIM routers