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.18 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 register-accept-list PLIST
70 When pim receives a register packet the source of the packet will be compared
71 to the prefix-list specified, PLIST, and if a permit is received normal
72 processing continues. If a deny is returned for the source address of the
73 register packet a register stop message is sent to the source.
75 .. clicmd:: ip pim spt-switchover infinity-and-beyond
77 On the last hop router if it is desired to not switch over to the SPT tree.
78 Configure this command. This command is vrf aware, to configure for a vrf,
79 enter the vrf submode.
81 .. clicmd:: ip pim ecmp
83 If pim has the a choice of ECMP nexthops for a particular RPF, pim will
84 cause S,G flows to be spread out amongst the nexthops. If this command is
85 not specified then the first nexthop found will be used. This command is vrf
86 aware, to configure for a vrf, enter the vrf submode.
88 .. clicmd:: ip pim ecmp rebalance
90 If pim is using ECMP and an interface goes down, cause pim to rebalance all
91 S,G flows across the remaining nexthops. If this command is not configured
92 pim only modifies those S,G flows that were using the interface that went
93 down. This command is vrf aware, to configure for a vrf, enter the vrf
96 .. clicmd:: ip pim join-prune-interval (1-65535)
98 Modify the join/prune interval that pim uses to the new value. Time is
99 specified in seconds. This command is vrf aware, to configure for a vrf,
100 enter the vrf submode. The default time is 60 seconds. If you enter
101 a value smaller than 60 seconds be aware that this can and will affect
102 convergence at scale.
104 .. clicmd:: ip pim keep-alive-timer (1-65535)
106 Modify the time out value for a S,G flow from 1-60000 seconds. If choosing
107 a value below 31 seconds be aware that some hardware platforms cannot see data
108 flowing in better than 30 second chunks. This command is vrf aware, to
109 configure for a vrf, enter the vrf submode.
111 .. clicmd:: ip pim packets (1-255)
113 When processing packets from a neighbor process the number of packets
114 incoming at one time before moving on to the next task. The default value is
115 3 packets. This command is only useful at scale when you can possibly have
116 a large number of pim control packets flowing. This command is vrf aware, to
117 configure for a vrf, enter the vrf submode.
119 .. clicmd:: ip pim register-suppress-time (1-65535)
121 Modify the time that pim will register suppress a FHR will send register
122 notifications to the kernel. This command is vrf aware, to configure for a
123 vrf, enter the vrf submode.
125 .. clicmd:: ip pim send-v6-secondary
127 When sending pim hello packets tell pim to send any v6 secondary addresses
128 on the interface. This information is used to allow pim to use v6 nexthops
129 in it's decision for RPF lookup. This command is vrf aware, to configure for
130 a vrf, enter the vrf submode.
132 .. clicmd:: ip pim ssm prefix-list WORD
134 Specify a range of group addresses via a prefix-list that forces pim to
135 never do SM over. This command is vrf aware, to configure for a vrf, enter
138 .. clicmd:: ip multicast rpf-lookup-mode WORD
140 Modify how PIM does RPF lookups in the zebra routing table. You can use
144 Lookup the RPF in both tables using the longer prefix as a match
147 Lookup the RPF in both tables using the lower distance as a match
150 Lookup in the Multicast RIB only
153 Lookup in the Multicast RIB then the Unicast Rib, returning first found.
154 This is the default value for lookup if this command is not entered
157 Lookup in the Unicast Rib only.
159 .. clicmd:: ip igmp generate-query-once [version (2-3)]
161 Generate IGMP query (v2/v3) on user requirement. This will not depend on
162 the existing IGMP general query timer.If no version is provided in the cli,
163 it will be considered as default v2 query.This is a hidden command.
165 .. clicmd:: ip igmp watermark-warn (1-65535)
167 Configure watermark warning generation for an igmp group limit. Generates
168 warning once the configured group limit is reached while adding new groups.
169 'no' form of the command disables the warning generation. This command is
170 vrf aware. To configure per vrf, enter vrf submode.
172 .. _pim-interface-configuration:
174 PIM Interface Configuration
175 ===========================
177 PIM interface commands allow you to configure an interface as either a Receiver
178 or a interface that you would like to form pim neighbors on. If the interface
179 is in a vrf, enter the interface command with the vrf keyword at the end.
181 .. clicmd:: ip pim active-active
183 Turn on pim active-active configuration for a Vxlan interface. This
184 command will not do anything if you do not have the underlying ability
185 of a mlag implementation.
187 .. clicmd:: ip pim bsm
189 Tell pim that we would like to use this interface to process bootstrap
190 messages. This is enabled by default. 'no' form of this command is used to
191 restrict bsm messages on this interface.
193 .. clicmd:: ip pim unicast-bsm
195 Tell pim that we would like to allow interface to process unicast bootstrap
196 messages. This is enabled by default. 'no' form of this command is used to
197 restrict processing of unicast bsm messages on this interface.
199 .. clicmd:: ip pim drpriority (1-4294967295)
201 Set the DR Priority for the interface. This command is useful to allow the
202 user to influence what node becomes the DR for a lan segment.
204 .. clicmd:: ip pim hello (1-65535) (1-65535)
206 Set the pim hello and hold interval for a interface.
210 Tell pim that we would like to use this interface to form pim neighbors
211 over. Please note that this command does not enable the reception of IGMP
212 reports on the interface. Refer to the next `ip igmp` command for IGMP
215 .. clicmd:: ip pim use-source A.B.C.D
217 If you have multiple addresses configured on a particular interface
218 and would like pim to use a specific source address associated with
223 Tell pim to receive IGMP reports and Query on this interface. The default
224 version is v3. This command is useful on a LHR.
226 .. clicmd:: ip igmp join A.B.C.D [A.B.C.D]
228 Join multicast group or source-group on an interface.
230 .. clicmd:: ip igmp query-interval (1-65535)
232 Set the IGMP query interval that PIM will use.
234 .. clicmd:: ip igmp query-max-response-time (1-65535)
236 Set the IGMP query response timeout value. If an report is not returned in
237 the specified time we will assume the S,G or \*,G has timed out.
239 .. clicmd:: ip igmp version (2-3)
241 Set the IGMP version used on this interface. The default value is 3.
243 .. clicmd:: ip multicast boundary oil WORD
245 Set a pim multicast boundary, based upon the WORD prefix-list. If a pim join
246 or IGMP report is received on this interface and the Group is denied by the
247 prefix-list, PIM will ignore the join or report.
249 .. clicmd:: ip igmp last-member-query-count (1-255)
251 Set the IGMP last member query count. The default value is 2. 'no' form of
252 this command is used to to configure back to the default value.
254 .. clicmd:: ip igmp last-member-query-interval (1-65535)
256 Set the IGMP last member query interval in deciseconds. The default value is
257 10 deciseconds. 'no' form of this command is used to to configure back to the
260 .. clicmd:: ip mroute INTERFACE A.B.C.D [A.B.C.D]
262 Set a static multicast route for a traffic coming on the current interface to
263 be forwarded on the given interface if the traffic matches the group address
264 and optionally the source address.
269 :ref:`bfd-pim-peer-config`
272 .. _pim-multicast-rib:
277 In order to influence Multicast RPF lookup, it is possible to insert
278 into zebra routes for the Multicast RIB. These routes are only
279 used for RPF lookup and will not be used by zebra for insertion
280 into the kernel *or* for normal rib processing. As such it is
281 possible to create weird states with these commands. Use with
282 caution. Most of the time this will not be necessary.
284 .. clicmd:: ip mroute A.B.C.D/M A.B.C.D (1-255)
286 Insert into the Multicast Rib Route A.B.C.D/M with specified nexthop. The
287 distance can be specified as well if desired.
289 .. clicmd:: ip mroute A.B.C.D/M INTERFACE (1-255)
291 Insert into the Multicast Rib Route A.B.C.D/M using the specified INTERFACE.
292 The distance can be specified as well if desired.
294 .. _msdp-configuration:
296 Multicast Source Discovery Protocol (MSDP) Configuration
297 ========================================================
299 MSDP can be setup in different ways:
301 * MSDP meshed-group: where all peers are connected with each other creating
302 a fully meshed network. SAs (source active) messages are not forwarded in
303 this mode because the origin is able to send SAs to all members.
305 This setup is commonly used with anycast.
307 * MSDP peering: when there is one or more peers that are not fully meshed. SAs
308 may be forwarded depending on the result of filtering and RPF checks.
310 This setup is commonly consistent with BGP peerings (for RPF checks).
312 * MSDP default peer: there is only one peer and all SAs will be forwarded
317 MSDP default peer and SA filtering is not implemented.
320 Commands available for MSDP:
322 .. clicmd:: ip msdp timers (1-65535) (1-65535) [(1-65535)]
324 Configure global MSDP timers.
326 First value is the keep-alive interval. This configures the interval in
327 seconds between keep-alive messages. The default value is 60 seconds. It
328 should be less than the remote hold time.
330 Second value is the hold-time. This configures the interval in seconds before
331 closing a non responding connection. The default value is 75. This value
332 should be greater than the remote keep alive time.
334 Third value is the connection retry interval and it is optional. This
335 configures the interval between connection attempts. The default value
338 .. clicmd:: ip msdp mesh-group WORD member A.B.C.D
340 Create or update a mesh group to include the specified MSDP peer.
342 .. clicmd:: ip msdp mesh-group WORD source A.B.C.D
344 Create or update a mesh group to set the source address used to connect to
347 .. clicmd:: ip msdp peer A.B.C.D source A.B.C.D
349 Create a regular MSDP session with peer using the specified source address.
352 .. _show-pim-information:
357 All PIM show commands are vrf aware and typically allow you to insert a
358 specified vrf command if information is desired about a specific vrf. If no
359 vrf is specified then the default vrf is assumed. Finally the special keyword
360 'all' allows you to look at all vrfs for the command. Naming a vrf 'all' will
361 cause great confusion.
363 .. clicmd:: show ip igmp interface
365 Display IGMP interface information.
367 .. clicmd:: show ip igmp [vrf NAME] join [json]
369 Display IGMP static join information for a specific vrf.
370 If "vrf all" is provided, it displays information for all the vrfs present.
372 .. clicmd:: show ip igmp groups
374 Display IGMP groups information.
376 .. clicmd:: show ip igmp groups retransmissions
378 Display IGMP group retransmission information.
380 .. clicmd:: show ip igmp [vrf NAME] sources [json]
382 Display IGMP sources information.
384 .. clicmd:: show ip igmp sources retransmissions
386 Display IGMP source retransmission information.
388 .. clicmd:: show ip igmp statistics
390 Display IGMP statistics information.
392 .. clicmd:: show ip multicast
394 Display various information about the interfaces used in this pim instance.
396 .. clicmd:: show ip mroute [vrf NAME] [A.B.C.D [A.B.C.D]] [fill] [json]
398 Display information about installed into the kernel S,G mroutes. If
399 one address is specified we assume it is the Group we are interested
400 in displaying data on. If the second address is specified then it is
401 Source Group. The keyword `fill` says to fill in all assumed data
402 for test/data gathering purposes.
404 .. clicmd:: show ip mroute [vrf NAME] count [json]
406 Display information about installed into the kernel S,G mroutes and in
407 addition display data about packet flow for the mroutes for a specific
410 .. clicmd:: show ip mroute vrf all count [json]
412 Display information about installed into the kernel S,G mroutes and in
413 addition display data about packet flow for the mroutes for all vrfs.
415 .. clicmd:: show ip mroute [vrf NAME] summary [json]
417 Display total number of S,G mroutes and number of S,G mroutes installed
418 into the kernel for a specific vrf.
420 .. clicmd:: show ip mroute vrf all summary [json]
422 Display total number of S,G mroutes and number of S,G mroutes
423 installed into the kernel for all vrfs.
425 .. clicmd:: show ip msdp mesh-group
427 Display the configured mesh-groups, the local address associated with each
428 mesh-group, the peer members included in each mesh-group, and their status.
430 .. clicmd:: show ip msdp peer
432 Display information about the MSDP peers. That includes the peer address,
433 the local address used to establish the connection to the peer, the
434 connection status, and the number of active sources.
436 .. clicmd:: show ip pim assert
438 Display information about asserts in the PIM system for S,G mroutes.
440 .. clicmd:: show ip pim assert-internal
442 Display internal assert state for S,G mroutes
444 .. clicmd:: show ip pim assert-metric
446 Display metric information about assert state for S,G mroutes
448 .. clicmd:: show ip pim assert-winner-metric
450 Display winner metric for assert state for S,G mroutes
452 .. clicmd:: show ip pim group-type
454 Display SSM group ranges.
456 .. clicmd:: show ip pim interface
458 Display information about interfaces PIM is using.
460 .. clicmd:: show ip pim mlag [vrf NAME|all] interface [detail|WORD] [json]
462 Display mlag interface information.
464 .. clicmd:: show ip pim join
466 Display information about PIM joins received. If one address is specified
467 then we assume it is the Group we are interested in displaying data on.
468 If the second address is specified then it is Source Group.
470 .. clicmd:: show ip pim local-membership
472 Display information about PIM interface local-membership.
474 .. clicmd:: show ip pim mlag summary [json]
476 Display mlag information state that PIM is keeping track of.
478 .. clicmd:: show ip pim neighbor
480 Display information about PIM neighbors.
482 .. clicmd:: show ip pim nexthop
484 Display information about pim nexthops that are being used.
486 .. clicmd:: show ip pim nexthop-lookup
488 Display information about a S,G pair and how the RPF would be chosen. This
489 is especially useful if there are ECMP's available from the RPF lookup.
491 .. clicmd:: show ip pim rp-info
493 Display information about RP's that are configured on this router.
495 .. clicmd:: show ip pim rpf
497 Display information about currently being used S,G's and their RPF lookup
498 information. Additionally display some statistics about what has been
499 happening on the router.
501 .. clicmd:: show ip pim secondary
503 Display information about an interface and all the secondary addresses
506 .. clicmd:: show ip pim state
508 Display information about known S,G's and incoming interface as well as the
509 OIL and how they were chosen.
511 .. clicmd:: show ip pim [vrf NAME] upstream [A.B.C.D [A.B.C.D]] [json]
513 Display upstream information about a S,G mroute. Allow the user to
514 specify sub Source and Groups that we are only interested in.
516 .. clicmd:: show ip pim upstream-join-desired
518 Display upstream information for S,G's and if we desire to
519 join the multicast tree
521 .. clicmd:: show ip pim upstream-rpf
523 Display upstream information for S,G's and the RPF data associated with them.
525 .. clicmd:: show ip pim [vrf NAME] mlag upstream [A.B.C.D [A.B.C.D]] [json]
527 Display upstream entries that are synced across MLAG switches.
528 Allow the user to specify sub Source and Groups address filters.
530 .. clicmd:: show ip pim mlag summary
532 Display PIM MLAG (multi-chassis link aggregation) session status and
533 control message statistics.
535 .. clicmd:: show ip pim bsr
537 Display current bsr, its uptime and last received bsm age.
539 .. clicmd:: show ip pim bsrp-info
541 Display group-to-rp mappings received from E-BSR.
543 .. clicmd:: show ip pim bsm-database
545 Display all fragments ofstored bootstrap message in user readable format.
547 .. clicmd:: mtrace A.B.C.D [A.B.C.D]
549 Display multicast traceroute towards source, optionally for particular group.
551 .. clicmd:: show ip multicast count [vrf NAME] [json]
553 Display multicast data packets count per interface for a vrf.
555 .. clicmd:: show ip multicast count vrf all [json]
557 Display multicast data packets count per interface for all vrf.
562 :ref:`multicast-rib-commands`
568 The debugging subsystem for PIM behaves in accordance with how FRR handles
569 debugging. You can specify debugging at the enable CLI mode as well as the
570 configure CLI mode. If you specify debug commands in the configuration cli
571 mode, the debug commands can be persistent across restarts of the FRR pimd if
572 the config was written out.
574 .. clicmd:: debug igmp
576 This turns on debugging for IGMP protocol activity.
578 .. clicmd:: debug mtrace
580 This turns on debugging for mtrace protocol activity.
582 .. clicmd:: debug mroute
584 This turns on debugging for PIM interaction with kernel MFC cache.
586 .. clicmd:: debug pim events
588 This turns on debugging for PIM system events. Especially timers.
590 .. clicmd:: debug pim nht
592 This turns on debugging for PIM nexthop tracking. It will display
593 information about RPF lookups and information about when a nexthop changes.
595 .. clicmd:: debug pim packet-dump
597 This turns on an extraordinary amount of data. Each pim packet sent and
598 received is dumped for debugging purposes. This should be considered a
599 developer only command.
601 .. clicmd:: debug pim packets
603 This turns on information about packet generation for sending and about
604 packet handling from a received packet.
606 .. clicmd:: debug pim trace
608 This traces pim code and how it is running.
610 .. clicmd:: debug pim bsm
612 This turns on debugging for BSR message processing.
614 .. clicmd:: debug pim zebra
616 This gathers data about events from zebra that come up through the ZAPI.
620 Clear commands reset various variables.
622 .. clicmd:: clear ip interfaces
626 .. clicmd:: clear ip igmp interfaces
628 Reset IGMP interfaces.
630 .. clicmd:: clear ip mroute
632 Reset multicast routes.
634 .. clicmd:: clear ip mroute [vrf NAME] count
636 When this command is issued, reset the counts of data shown for
637 packet count, byte count and wrong interface to 0 and start count
640 .. clicmd:: clear ip pim interfaces
642 Reset PIM interfaces.
644 .. clicmd:: clear ip pim oil
646 Rescan PIM OIL (output interface list).
648 .. clicmd:: clear ip pim [vrf NAME] bsr-data
650 This command will clear the BSM scope data struct. This command also
651 removes the next hop tracking for the bsr and resets the upstreams
652 for the dynamically learnt RPs.
654 PIM EVPN configuration
655 ======================
656 To use PIM in the underlay for overlay BUM forwarding associate a multicast
657 group with the L2 VNI. The actual configuration is based on your distribution.
658 Here is an ifupdown2 example::
664 vxlan-local-tunnelip 27.0.0.11
665 vxlan-mcastgrp 239.1.1.100
669 PIM will see the ``vxlan-mcastgrp`` configuration and auto configure state
670 to properly forward BUM traffic.
672 PIM also needs to be configured in the underlay to allow the BUM MDT to be
673 setup. This is existing PIM configuration:
675 - Enable pim on the underlay L3 interface via the "ip pim" command.
676 - Configure RPs for the BUM multicast group range.
677 - Ensure the PIM is enabled on the lo of the VTEPs and the RP.
689 ! You may want to enable ssmpingd for troubleshooting
690 ! See http://www.venaas.no/multicast/ssmping/
696 ! - Enable "ip pim ssm" on the interface directly attached to the
697 ! multicast source host (if this is the first-hop router)
698 ! - Enable "ip pim ssm" on pim-routers-facing interfaces
699 ! - Enable "ip igmp" on IGMPv3-hosts-facing interfaces
700 ! - In order to inject IGMPv3 local membership information in the
701 ! PIM protocol state, enable both "ip pim ssm" and "ip igmp" on
702 ! the same interface; otherwise PIM won't advertise
703 ! IGMPv3-learned membership to other PIM routers