1PIMD(8) System Manager's Manual PIMD(8)
2
4 pimd — PIM-SM/SSM v2 dynamic multicast routing daemon
5
7 pimd [-fhlNqr] [-c FILE] [-d [SYS[,SYS,...]] [-s LEVEL]
8
10 pimd is a lightweight, stand-alone PIM-SM/SSM v2 multicast routing daemon
11 available under the free 3-clause BSD license. This is the restored
12 original from University of Southern California, by Ahmed Helmy, Rusty
13 Eddy and Pavlin Ivanov Radoslavov.
14 Protocol Independent Multicast - Sparse Mode (PIM-SM):
16 · maintains the traditional IP multicast service model of receiver-ini‐
17 tiated membership;
18 · uses explicit joins that propagate hop-by-hop from members' directly
19 connected routers toward the distribution tree.
20 · builds a shared multicast distribution tree centered at a Rendezvous
21 Point (RP), and then builds source-specific trees for those sources
22 whose data traffic warrants it.
23 · is not dependent on a specific unicast routing protocol; and
24 · uses soft-state mechanisms to adapt to underlying network conditions
25 and group dynamics.
26 The robustness, flexibility, and scaling properties of this architecture
28 make it well suited to large heterogeneous internetworks.
29 pimd originally only implemented RFC2362, but since v2.3.0 is supporting
31 more and more of RFC4601.
32
34 This program follows the usual UNIX command line syntax, with long
35 options starting with two dashes (`-'). The options are as follows:
36 -h, --help
38 Print a help message and exit.
39 -c, --config=FILE
41 Specify an alternative configuration file, default
42 /etc/pimd.conf. If pimd cannot find its configuration file it
43 will start up with fallback defaults, which include enabling both
44 bsr-candidate and rp-candidate.
45 -d, --debug[=SYS[,SYS...]
47 By default, pimd daemonizes itself by detaching from the invoking
48 terminal and forking to the background. However, if -d, --debug
49 or -f, --foreground is specified, pimd runs in the foreground of
50 the starting terminal. If -d is given without any argument pimd
51 defaults to debug all subystems.
52 Available subsystems are:
54 packet Debug inbound/outbout packets
56 prunes Pruning operations, or pruned routes
57 routes Routing messages
58 rtdetail Detailed routing information
59 peers Neighbor gossip
60 cache Debug routing cache
61 timeout Debug timeouts
62 interface Show interface (VIF) debug messages
63 groups Debug group memberships
64 mtrace Multicast traceroute information
65 igmp Debug IGMP messages
66 icmp Debug ICMP messages
67 rsrr Debug RSRR messages
68 pim All PIM messages
69 pim_routes PIM routing messages
70 pim_bsr PIM bootstrap router messages
71 pim_detail Detailed PIM debug
72 pim_hello Debug hello messages to/from neighbors
73 -f, --foreground
75 Run in the foreground, do not detach from calling terminal and do
76 not fork to background. Useful not only when debugging (above)
77 but also when running under a process monitor like daemontools,
78 runit, finit, or systemd.
79 -l, --reload-config
81 Tell a running pimd to reload its configuration. This is done by
82 sending a SIGHUP to the PID listed in /var/run/pimd.pid. Depend‐
83 ing on the capabilities of your user, you may need to be root to
84 do this.
85 -N, --disable-vifs
87 This prevents pimd from being activated on all interfaces by
88 default. When this command line option is given, use `phyint
89 IFNAME enable` to selectively activate PIM services on an inter‐
90 face.
91 -q, --quit-daemon
93 Tell a running pimd to quit. Similar to -l, --reload-config but
94 this command sends SIGTERM. Depending on the capabilities of
95 your user, you may need to be root to do this.
96 -r, --show-routes
98 Show state of VIFs and multicast routing tables. This is command
99 sends SIGUSR1 to a running pimd, similar to -l --reload-config.
100 Depending on the capabilities of your user, you may need to be
101 root to do this.
102 -v, --version
104 Show pimd version
105 -s, --loglevel=LEVEL
107 Set log level to one of the following, default notice:
108 none Disable all logging
110 error Error conditions
111 warning Warning conditions
112 notice Normal but significant condition (Default)
113 info Informational
114 debug Debug-level messages
115
117 The configuration is kept in the file /etc/pimd.conf. The file format is
118 relatively free-form: whitespace (including newlines) is not significant.
119 However, the order of some statements are important, see more below.
120 All <masklen> arguments to an IPv4 address, group or network can also be
122 given in the alternative /CIDR format. E.g., <group>/<masklen>.
123 Here are the different configuration settings:
125 default-route-distance <1-255>
127 default-route-metric <1-1024>
129 igmp-query-interval <1-65535>
131 igmp-querier-timeout <8-65535>
133 hello-interval <30-18724>
135 phyint <address | ifname>
137 [disable | enable] [igmpv2 | igmpv3]
138 [dr-priority <1-4294967294>]
139 [ttl-threshold <1-255>] [distance <1-255>] [metric <1-1024>]
140 [altnet <network> [/<masklen> | masklen <masklen>]]
141 [scoped <network> [/<masklen> | masklen <masklen>]]
142 bsr-candidate [address | ifname] [priority <number>]
144 rp-candidate [address | ifname] [priority <0-255>] [time
146 <10-16384>]
147 group-prefix <group>[/<masklen> | masklen <masklen>]
148 ...
149 group-prefix ...
150 rp-address <address> [<group-addr>[/<masklen> | masklen <masklen]
152 spt-threshold [rate <KBPS> | packets <NUM> | infinity] [interval
154 <SEC>]
155 By default, pimd will be activated on all multicast capable interfaces.
157 The phyint setting and the -N, --disable-vifs command line option control
158 this behaviour. More on the phyint interface configuration setting
159 below.
160 The default-route-distance option has nothing to do with the system
162 default route, it is rather the default value for the unicast routing
163 protocol's administrative distance. It is used in PIM Assert elections
164 to determine upstream routers. Currently pimd cannot obtain the admin
165 distance and metric from the unicast routing protocols, so a default
166 routing protocol distance (the RFC confusingly refers to this as metric
167 prefererence) may be configured. In a PIM Assert election, the router
168 advertising the lowest assert preference will be selected as the for‐
169 warder and upstream router for the LAN. Setting 101 should be suffi‐
170 ciently high so that asserts from Cisco or GateD routers are preferred
171 over poor-little pimd.
172 It is reccommended that distances be set such that metrics are never con‐
174 sulted. However, default routing metrics may also be set using the
175 default-route-metric option. (Again, this has nothing to do with the
176 system default route.) This item sets the cost for sending data through
177 this router. You want only PIM-SM data to go to this daemon; so once
178 again, a high value is recommended to prevent accidental usage. The pre‐
179 ferred default value is 1024. Both defaults can be overridden per
180 phyint, so learned routes, or PIM Asserts use the phyint's values.
181 Please also note that PIM Assert elections are not the same as the DR
183 election. The PIM Assert election determines the active multicast for‐
184 warder, whereas the DR election determines the active PIM router.
185 Two settings for IGMP behavior are available: igmp-query-interval and
187 igmp-querier-timeout which are similar, but very different. The former
188 controls the interval between IGMP querys when elected as querier, the
189 latter controls the timeout for the elected querier -- before pimd
190 decides to take over. In IGMP the lowest numerical address in a LAN
191 becomes the elected querier. Obviously these settings must be handled
192 with care. The RFC recommends that the querier timeout is set to a
193 robustness value times the query interval, plus have the query response
194 time. The pimd robustness value for IGMP is 3 and the default query
195 response time is 10 sec. Since pimd v2.3.0 the default query interval is
196 12 sec, which makes the querier timeut default to 41 sec, but this is
197 rounded off to 42 to honor the late Douglas Adams.
198 The PIM Hello message interval can be tuned by changing the
200 hello-interval setting. Changing this value also affects the hold-time
201 value included in Hello messages. The hold-time value is 3.5 times
202 hello-interval. The default value for the Hello interval is 30 sec.
203 Anything less than 30 sec is considered an "aggressive" setting and is
204 unsupported.
205 The phyint option refers to a physical interface and must come after
207 default-route-metric and default-route-distance. Select the interface
208 either by its IP address or interface name ifname (e.g. eth0). If you
209 just want to activate this interface with default values, you don't need
210 to put anything else on the line. However, there are some additional
211 settings:
212 · disable: Do not send PIM-SM traffic through this interface nor
213 listen for PIM-SM traffic from this interface. Default: enable.
214 enable: Selectively enable which interfaces to send PIM-SM traf‐
215 fic through. Useful with the -N command line option.
216 · igmpv2: Force interface to use IGMPv2, or
217 · igmpv3: Use IGMPv3, this is the default since v2.3.0.
218 · dr-priority <1-4294967294>: When there are multiple PIM routers
219 on the same LAN the DR is usually elected based on the highest
220 numerical IP address. This setting can be used to control the
221 DR Priority option in PIM Hellow messages, which by default oth‐
222 erwise is 1. When the DR Priority option is advertised by all
223 PIM routers on the same LAN the highest priority router wins the
224 DR election, regardless of its IP. If any router does not
225 advertise the DR Priority option, or the same priority is adver‐
226 tised by more than one router, the protocol falls back to using
227 the IP address.
228 · ttl-threshold <1-255>: The TTL threshold for multicast frames to
229 be forwarded from this interface. Default: 1
230 · distance <1-255>: Use this to override the
231 default-route-distance (101) on this phyint in PIM Assert elec‐
232 tions.
233 · metric <1-1024>: The cost of sending data through this inter‐
234 face. Defaults to default-route-metric (1024) if not assigned.
235 · altnet <network/len>: Alternative host(s)/network(s) to accept
236 as locally attached multicast sources on a given interface. If a
237 phyint is attached to multiple IP subnets, describe each addi‐
238 tional subnet with the altnet keyword.
239 · scoped <network/len>: Optional scoping of multicast groups. This
240 allows interfaces to be configured as an administrative boundary
241 for the specified group(s). Multicast streams belonging to the
242 scoped groups will not be forwarded.
243 Add one phyint line per interface on this router. If you don't do this,
245 pimd will either be completely silent (if you provide the -N command line
246 option), or simply assume that you want it to utilize all interfaces
247 using default settings.
248 Both the bsr-candidate (CBSR) and rp-candidate (CRP) settings are enabled
250 in the default configuration. Disabling them, by commenting them out in
251 the config file, for all PIM capable routers is a bad idea. When trou‐
252 bleshooting, ensure at least one bootstrap router (BSR) and at least one
253 rendez-vous point (RP) in PIM-SM, is available. Both settings share the
254 following options, with priority being interpreted differently:
255 · address | ifname: Optional local IPv4 address, or interface name
257 to acquire address from. If both address and ifname is left
258 out, pimd will default to the highest active IP address.
259 · priority <0-255>: How important this router is compared to oth‐
260 ers. For CRP, the lower the value the more important the router
261 is considered. For BSR it is of course the exact opposite: a
262 higher value is preferred. If the priority is left out pimd and
263 Cisco IOS defaults to 0 for both, but the standard says 192 for
264 RP.
265 · time <10-16383>: The number of seconds to wait between advertis‐
266 ing this CRP. The default value is 30 seconds. Use a lower
267 value for faster convergence.
268 The group-prefix sub-setting to rp-candidate is the set of multi‐
270 cast groups that the CRP will advertise to other routers, if it
271 wins an election:
272 · group: A specific multicast group or network range this
273 router will handle.
274 · masklen: Optional number of groups, in prefix length for‐
275 mat. Remember that a multicast address is a Class D and
276 has a netmask of 240.0.0.0, which means its length is 4.
277 Multiple lines of group-prefix may be given, but max number of
279 records supported in pimd is 255.
280 The rp-address setting is for static rendezvous point (RP) configura‐
282 tions. It defines the RP for a given group, or range or groups. The
283 argument can be either a unicast address or a multicast group, with an
284 optional group address and netmask. Default group and netmask is
285 224.0.0.0/16. Note: all static RP's are announced with priority 1.
286 The spt-threshold setting replaces two older configuration settings,
288 switch_data_threshold and switch_register_threshold. It controls the
289 switch-over from the shared tree to the shortest-path source tree. The
290 default is to do the switch-over after the first packet, but only after
291 100 seconds. If infinity is specified the shortest path switch-over is
292 disabled.
293
295 pimd responds to the following signals:
296 HUP Restarts pimd. The configuration file is reread every time this
298 signal is evoked.
299 TERM Terminates execution gracefully (i.e. by sending good-bye messages
300 to all neighboring routers).
301 INT The same as TERM.
302 USR1 Dumps the internal state of VIFs and multicast routing tables to
303 /var/run/pimd/pimd.dump. See also the -r, --show-routes option
304 above.
305 For convenience in sending signals, pimd writes its process ID to
307 /var/run/pimd.pid upon startup.
308
310 /etc/pimd.conf
311 /var/run/pimd/pimd.dump
312 /var/run/pimd.pid
313
315 mrouted(8), smcroute(8), /usr/share/doc/pimd/
316 PIM-SM is described in, the now obsolete RFC2362, and the current
318 RFC4601, with additions in RFC5059 and RFC5796.
319 The pages at USC, http://netweb.usc.edu/pim/, are unfortunately no longer
321 available. The wiki pages at http://github.com/troglobit/pimd/, the new
322 GitHub project, are an attempt to gather as much info as possible.
323
325 pimd was written by Ahmed Helmy, George Edmond "Rusty" Eddy, and Pavlin
326 Ivanov Radoslavov. PIM-SSM, including full IGMPv3 support, added by
327 Markus Veranen. With contributions by many others.
328 This manual page was initially written by Antonín Král for the Debian
330 GNU/Linux system, and then updated by Joachim Nilsson for the GitHub pimd
331 project.
332BSD Mar 3, 2016 BSD