1: .\" Hey, EMACS: -*- nroff -*-
2: .\" First parameter, NAME, should be all caps
3: .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
4: .\" other parameters are allowed: see man(7), man(1)
5: .Dd Mar 3, 2016
6: .\" Please adjust this date whenever revising the manpage.
7: .Dt PIMD 8 SMM
8: .Os
9: .Sh NAME
10: .Nm pimd
11: .Nd PIM-SM/SSM v2 dynamic multicast routing daemon
12: .Sh SYNOPSIS
13: .Nm pimd
14: .Op Fl fhlNqr
15: .Op Fl c Ar FILE
16: .Op Fl d Ar [SYS[,SYS,...]
17: .Op Fl s Ar LEVEL
18: .Sh DESCRIPTION
19: .Nm
20: is a lightweight, stand-alone PIM-SM/SSM v2 multicast routing daemon
21: available under the free 3-clause BSD license. This is the restored
22: original from University of Southern California, by Ahmed Helmy, Rusty
23: Eddy and Pavlin Ivanov Radoslavov.
24: .Pp
25: Protocol Independent Multicast - Sparse Mode (PIM-SM):
26: .Bl -bullet -width 1n -compact
27: .It
28: maintains the traditional IP multicast service model of
29: receiver-initiated membership;
30: .It
31: uses explicit joins that propagate hop-by-hop from members' directly
32: connected routers toward the distribution tree.
33: .It
34: builds a shared multicast distribution tree centered at a Rendezvous
35: Point (RP), and then builds source-specific trees for those sources
36: whose data traffic warrants it.
37: .It
38: is not dependent on a specific unicast routing protocol; and
39: .It
40: uses soft-state mechanisms to adapt to underlying network conditions and
41: group dynamics.
42: .El
43: .Pp
44: The robustness, flexibility, and scaling properties of this architecture
45: make it well suited to large heterogeneous internetworks.
46: .Pp
47: .Nm
48: originally only implemented RFC2362, but since v2.3.0 is supporting more
49: and more of RFC4601.
50: .Sh OPTIONS
51: This program follows the usual UNIX command line syntax, with long
52: options starting with two dashes (`-'). The options are as follows:
53: .Bl -tag -width Ds
54: .It Fl h, -help
55: Print a help message and exit.
56: .It Fl c, -config=FILE
57: Specify an alternative configuration file, default
58: .Pa /etc/pimd.conf .
59: If
60: .Nm
61: cannot find its configuration file it will start up with fallback
62: defaults, which include enabling both
63: .Cm bsr-candidate
64: and
65: .Cm rp-candidate .
66: .It Fl d, -debug[=SYS[,SYS...]
67: By default,
68: .Nm
69: daemonizes itself by detaching from the invoking terminal and forking to
70: the background. However, if
71: .Fl d, -debug
72: or
73: .Fl f, -foreground
74: is specified,
75: .Nm
76: runs in the foreground of the starting terminal. If
77: .Fl d
78: is given without any argument
79: .Nm
80: defaults to debug all subystems.
81: .Pp
82: Available subsystems are:
83: .Pp
84: .Bl -tag -width pim_routes -compact -offset indent
85: .It Cm packet
86: Debug inbound/outbout packets
87: .It Cm prunes
88: Pruning operations, or pruned routes
89: .It Cm routes
90: Routing messages
91: .It Cm rtdetail
92: Detailed routing information
93: .It Cm peers
94: Neighbor gossip
95: .It Cm cache
96: Debug routing cache
97: .It Cm timeout
98: Debug timeouts
99: .It Cm interface
100: Show interface (VIF) debug messages
101: .It Cm groups
102: Debug group memberships
103: .It Cm mtrace
104: Multicast traceroute information
105: .It Cm igmp
106: Debug IGMP messages
107: .It Cm icmp
108: Debug ICMP messages
109: .It Cm rsrr
110: Debug RSRR messages
111: .It Cm pim
112: All PIM messages
113: .It Cm pim_routes
114: PIM routing messages
115: .It Cm pim_bsr
116: PIM bootstrap router messages
117: .It Cm pim_detail
118: Detailed PIM debug
119: .It Cm pim_hello
120: Debug hello messages to/from neighbors
121: .El
122: .It Fl f, -foreground
123: Run in the foreground, do not detach from calling terminal and do not
124: fork to background. Useful not only when debugging (above) but also
125: when running under a process monitor like daemontools, runit, finit, or
126: systemd.
127: .It Fl l, -reload-config
128: Tell a running pimd to reload its configuration. This is done by sending
129: a SIGHUP to the PID listed in
130: .Pa /var/run/pimd.pid .
131: Depending on the capabilities of your user, you may need to be root to
132: do this.
133: .It Fl N, -disable-vifs
134: This prevents
135: .Nm
136: from being activated on all interfaces by default. When this command
137: line option is given, use `phyint IFNAME enable` to selectively activate
138: PIM services on an interface.
139: .It Fl q, -quit-daemon
140: Tell a running
141: .Nm
142: to quit. Similar to
143: .Fl l, -reload-config
144: but this command sends SIGTERM. Depending on the capabilities of your
145: user, you may need to be root to do this.
146: .It Fl r, -show-routes
147: Show state of VIFs and multicast routing tables. This is command sends
148: SIGUSR1 to a running
149: .Nm ,
150: similar to
151: .Fl l -reload-config.
152: Depending on the capabilities of your user, you may need to be root to
153: do this.
154: .It Fl v, -version
155: Show
156: .Nm
157: version
158: .It Fl s, -loglevel=LEVEL
159: Set log level to one of the following, default
160: .Nm notice :
161: .Pp
162: .Bl -tag -width WARNING -compact -offset indent
163: .It Cm none
164: Disable all logging
165: .It Cm error
166: Error conditions
167: .It Cm warning
168: Warning conditions
169: .It Cm notice
170: Normal but significant condition (Default)
171: .It Cm info
172: Informational
173: .It Cm debug
174: Debug-level messages
175: .El
176: .El
177: .Sh CONFIGURATION
178: The configuration is kept in the file
179: .Pa /etc/pimd.conf .
180: The file format is relatively free-form: whitespace (including newlines) is not
181: significant. However, the order of some statements are important, see
182: more below.
183: .Pp
184: All <masklen> arguments to an IPv4 address, group or network can also be
185: given in the alternative /CIDR format. E.g., <group>/<masklen>.
186: .Pp
187: Here are the different configuration settings:
188: .Bl -item -offset indent
189: .It
190: .Cm default-route-distance
191: .Ar <1-255>
192: .It
193: .Cm default-route-metric
194: .Ar <1-1024>
195: .It
196: .Cm igmp-query-interval
197: .Ar <1-65535>
198: .It
199: .Cm igmp-querier-timeout
200: .Ar <8-65535>
201: .It
202: .Cm hello-interval
203: .Ar <30-18724>
204: .It
205: .Cm phyint
206: .Cm <address | ifname>
207: .Bl -item -offset indent
208: .Op Cm disable | enable
209: .Op Cm igmpv2 | igmpv3
210: .br
211: .Op Cm dr-priority Ar <1-4294967294>
212: .br
213: .Op Cm ttl-threshold Ar <1-255>
214: .Op Cm distance Ar <1-255>
215: .Op Cm metric Ar <1-1024>
216: .br
217: .Oo
218: .Cm altnet Ar <network> Op Cm /<masklen> | Cm masklen <masklen>
219: .Oc
220: .br
221: .Oo
222: .Cm scoped Ar <network> Op Cm /<masklen> | Cm masklen <masklen>
223: .Oc
224: .El
225: .It
226: .Cm bsr-candidate
227: .Op Ar address | Ar ifname
228: .Op Cm priority Ar <number>
229: .It
230: .Cm rp-candidate
231: .Op Ar address | Ar ifname
232: .Op Cm priority Ar <0-255>
233: .Op Cm time Ar <10-16384>
234: .Bl -item -offset indent -compact
235: .It
236: .Cm group-prefix Ar <group>[/<masklen> | Cm masklen Ar <masklen>]
237: .It
238: ...
239: .It
240: .Cm group-prefix ...
241: .El
242: .It
243: .Cm rp-address Ar <address> [<group-addr>[/<masklen> | masklen <masklen]
244: .It
245: .Cm spt-threshold
246: .Op Cm rate Ar <KBPS> | Cm packets Ar <NUM> | Cm infinity
247: .Op Cm interval Ar <SEC>
248: .El
249: .Pp
250: By default,
251: .Nm
252: will be activated on all multicast capable interfaces. The
253: .Cm phyint
254: setting and the
255: .Fl N, -disable-vifs
256: command line option control this behaviour. More on the
257: .Cm phyint
258: interface configuration setting below.
259: .Pp
260: The
261: .Cm default-route-distance
262: option has nothing to do with the system default route, it is rather the
263: default value for the unicast routing protocol's administrative
264: distance. It is used in PIM Assert elections to determine upstream
265: routers. Currently
266: .Nm
267: cannot obtain the admin distance and metric from the unicast routing
268: protocols, so a default routing protocol distance (the RFC confusingly
269: refers to this as
270: .Em metric prefererence )
271: may be configured. In a PIM Assert election, the router advertising the
272: lowest assert preference will be selected as the forwarder and upstream
273: router for the LAN. Setting 101 should be sufficiently high so that
274: asserts from Cisco or GateD routers are preferred over poor-little pimd.
275: .Pp
276: It is reccommended that distances be set such that metrics are never
277: consulted. However, default routing metrics may also be set using the
278: .Cm default-route-metric
279: option. (Again, this has nothing to do with the system default route.)
280: This item sets the cost for sending data through this router. You want
281: only PIM-SM data to go to this daemon; so once again, a high value is
282: recommended to prevent accidental usage. The preferred default value is
283: 1024. Both defaults can be overridden per phyint, so learned routes, or
284: PIM Asserts use the phyint's values.
285: .Pp
286: Please also note that PIM Assert elections are not the same as the DR
287: election. The PIM Assert election determines the active multicast
288: forwarder, whereas the DR election determines the active PIM router.
289: .Pp
290: Two settings for IGMP behavior are available:
291: .Cm igmp-query-interval
292: and
293: .Cm igmp-querier-timeout
294: which are similar, but very different. The former controls the interval
295: between IGMP querys when elected as querier, the latter controls the
296: timeout for the elected querier -- before
297: .Nm pimd
298: decides to take over. In IGMP the lowest numerical address in a LAN
299: becomes the elected querier. Obviously these settings must be handled
300: with care. The RFC recommends that the querier timeout is set to a
301: robustness value times the query interval, plus have the query response
302: time. The pimd robustness value for IGMP is 3 and the default query
303: response time is 10 sec. Since pimd v2.3.0 the default query interval
304: is 12 sec, which makes the querier timeut default to 41 sec, but this is
305: rounded off to 42 to honor the late Douglas Adams.
306: .Pp
307: The PIM Hello message interval can be tuned by changing the
308: .Cm hello-interval
309: setting. Changing this value also affects the hold-time value included
310: in Hello messages. The hold-time value is 3.5 times hello-interval.
311: The default value for the Hello interval is 30 sec. Anything less than
312: 30 sec is considered an "aggressive" setting and is unsupported.
313: .Pp
314: The
315: .Nm phyint
316: option refers to a physical interface and must come after
317: .Cm default-route-metric
318: and
319: .Cm default-route-distance .
320: Select the interface either by its IP
321: .Ar address
322: or interface name
323: .Ar ifname
324: (e.g. eth0). If you just want to activate this interface with default
325: values, you don't need to put anything else on the line. However, there
326: are some additional settings:
327: .Bl -bullet -offset indent -width 1n -compact
328: .It
329: .Nm disable :
330: Do not send PIM-SM traffic through this interface nor listen for PIM-SM traffic
331: from this interface. Default: enable.
332: .Nm enable :
333: Selectively enable which interfaces to send PIM-SM traffic through. Useful with
334: the
335: .Fl N
336: command line option.
337: .It
338: .Nm igmpv2 :
339: Force interface to use IGMPv2, or
340: .It
341: .Nm igmpv3 :
342: Use IGMPv3, this is the default since v2.3.0.
343: .It
344: .Cm dr-priority Ar <1-4294967294> :
345: When there are multiple PIM routers on the same LAN the DR is usually
346: elected based on the highest numerical IP address. This setting can be
347: used to control the DR Priority option in PIM Hellow messages, which by
348: default otherwise is 1. When the DR Priority option is advertised by
349: .Em all
350: PIM routers on the same LAN the highest priority router wins the DR
351: election, regardless of its IP. If any router does
352: .Em not
353: advertise the DR Priority option, or the same priority is advertised by
354: more than one router, the protocol falls back to using the IP address.
355: .It
356: .Cm ttl-threshold Ar <1-255> :
357: The TTL threshold for multicast frames to be forwarded from this
358: interface. Default: 1
359: .It
360: .Cm distance Ar <1-255> :
361: Use this to override the
362: .Nm default-route-distance
363: (101) on this
364: .Nm phyint
365: in PIM Assert elections.
366: .It
367: .Cm metric Ar <1-1024> :
368: The cost of sending data through this interface. Defaults to
369: .Nm default-route-metric
370: (1024) if not assigned.
371: .It
372: .Cm altnet Ar <network/len> :
373: Alternative host(s)/network(s) to accept as locally attached multicast
374: sources on a given interface. If a phyint is attached to multiple IP
375: subnets, describe each additional subnet with the altnet keyword.
376: .It
377: .Cm scoped Ar <network/len> :
378: Optional scoping of multicast groups. This allows interfaces to be
379: configured as an administrative boundary for the specified
380: group(s). Multicast streams belonging to the scoped groups will not be
381: forwarded.
382: .El
383: .Pp
384: Add one
385: .Nm phyint
386: line per interface on this router. If you don't do this,
387: .Nm pimd
388: will either be completely silent (if you provide the
389: .Fl N
390: command line option), or simply assume that you want it to utilize all interfaces
391: using default settings.
392: .Pp
393: Both the
394: .Cm bsr-candidate
395: (CBSR) and
396: .Cm rp-candidate
397: (CRP) settings are enabled in the default configuration. Disabling
398: them, by commenting them out in the config file, for all PIM capable
399: routers is a bad idea. When troubleshooting, ensure at least one
400: bootstrap router (BSR) and at least one rendez-vous point (RP) in
401: PIM-SM, is available. Both settings share the following options, with
402: priority being interpreted differently:
403: .Pp
404: .Bl -bullet -offset indent -width 1n -compact
405: .It
406: .Nm address | ifname :
407: Optional local IPv4 address, or interface name to acquire address from.
408: If both address and ifname is left out,
409: .Nm
410: will default to the highest active IP address.
411: .It
412: .Nm priority Ar <0-255> :
413: How important this router is compared to others. For CRP, the lower the
414: value the more important the router is considered. For BSR it is of
415: course the exact opposite: a higher value is preferred. If the priority
416: is left out
417: .Nm
418: and Cisco IOS defaults to 0 for both, but the standard says 192 for RP.
419: .It
420: .Nm time Ar <10-16383> :
421: The number of seconds to wait between advertising this CRP. The default
422: value is 30 seconds. Use a lower value for faster convergence.
423: .El
424: .Pp
425: .Bl -item -offset indent -compact
426: .It
427: The
428: .Nm group-prefix
429: sub-setting to
430: .Nm rp-candidate
431: is the set of multicast groups that the CRP will advertise to other
432: routers, if it wins an election:
433: .Bl -bullet -offset indent -width 1n -compact
434: .It
435: .Nm group :
436: A specific multicast group or network range this router will handle.
437: .It
438: .Nm masklen :
439: Optional number of groups, in prefix length format. Remember that a
440: multicast address is a Class D and has a netmask of 240.0.0.0, which
441: means its length is 4.
442: .El
443: .Pp
444: Multiple lines of
445: .Nm group-prefix
446: may be given, but max number of records supported in pimd is 255.
447: .El
448: .Pp
449: The
450: .Nm rp-address
451: setting is for static rendezvous point (RP) configurations. It defines
452: the RP for a given group, or range or groups. The argument can be
453: either a unicast address or a multicast group, with an optional group
454: address and netmask. Default group and netmask is 224.0.0.0/16.
455: .Nm Note:
456: all static RP's are announced with priority 1.
457: .Pp
458: The
459: .Nm spt-threshold
460: setting replaces two older configuration settings,
461: .Nm switch_data_threshold
462: and
463: .Nm switch_register_threshold .
464: It controls the switch-over from the shared tree to the shortest-path
465: source tree. The default is to do the switch-over after the first
466: packet, but only after 100 seconds. If
467: .Ar infinity
468: is specified the shortest path switch-over is disabled.
469: .Sh SIGNALS
470: .Nm
471: responds to the following signals:
472: .Pp
473: .Bl -tag -width TERM -compact
474: .It HUP
475: Restarts
476: .Nm .
477: The configuration file is reread every time this signal is evoked.
478: .It TERM
479: Terminates execution gracefully (i.e. by sending good-bye messages to all neighboring
480: routers).
481: .It INT
482: The same as TERM.
483: .It USR1
484: Dumps the internal state of VIFs and multicast routing tables to
485: .Pa /var/run/pimd/pimd.dump .
486: See also the
487: .Fl r, -show-routes
488: option above.
489: .\" Not implemented yet, still TODO
490: .\" .It USR2
491: .\" Dumps the internal cache tables to
492: .\" .Pa /var/run/pimd/pimd.cache .
493: .\" Also not implemented yet, TODO
494: .\" .It QUIT
495: .\" Dumps the internal routing tables to stderr (only if
496: .\" .Nm
497: .\" was invoked with a non-zero debug level).
498: .El
499: .Pp
500: For convenience in sending signals,
501: .Nm
502: writes its process ID to
503: .Pa /var/run/pimd.pid
504: upon startup.
505: .Sh FILES
506: .Bl -tag -width /var/run/pimd/pimd.cache -compact
507: .It Pa /etc/pimd.conf
508: .\" .It Pa /var/run/pimd/pimd.cache
509: .It Pa /var/run/pimd/pimd.dump
510: .It Pa /var/run/pimd.pid
511: .El
512: .Sh SEE ALSO
513: .Xr mrouted 8 ,
514: .Xr smcroute 8 ,
515: .Xr /usr/share/doc/pimd/
516: .Pp
517: PIM-SM is described in, the now obsolete RFC2362, and the current
518: RFC4601, with additions in RFC5059 and RFC5796.
519: .Pp
520: The pages at USC, http://netweb.usc.edu/pim/, are unfortunately no
521: longer available. The wiki pages at http://github.com/troglobit/pimd/,
522: the new GitHub project, are an attempt to gather as much info as
523: possible.
524: .Sh AUTHORS
525: .Nm
526: was written by Ahmed Helmy, George Edmond "Rusty" Eddy, and Pavlin
527: Ivanov Radoslavov. PIM-SSM, including full IGMPv3 support, added by
528: Markus Veranen. With contributions by many others.
529: .Pp
530: This manual page was initially written by Antonín Král for the Debian
531: GNU/Linux system, and then updated by Joachim Nilsson for the GitHub
532: pimd project.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pimd.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pimd