1PIMD(8)                     System Manager's Manual                    PIMD(8)
2

NAME

4     pimd — PIM-SM/SSM v2 dynamic multicast routing daemon
5

SYNOPSIS

7     pimd [-fhlNqr] [-c FILE] [-d [SYS[,SYS,...]] [-s LEVEL]
8

DESCRIPTION

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
15     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
27     The robustness, flexibility, and scaling properties of this architecture
28     make it well suited to large heterogeneous internetworks.
29
30     pimd originally only implemented RFC2362, but since v2.3.0 is supporting
31     more and more of RFC4601.
32

OPTIONS

34     This program follows the usual UNIX command line syntax, with long
35     options starting with two dashes (`-').  The options are as follows:
36
37     -h, --help
38             Print a help message and exit.
39
40     -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
46     -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
53             Available subsystems are:
54
55                   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
74     -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
80     -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
86     -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
92     -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
97     -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
103     -v, --version
104             Show pimd version
105
106     -s, --loglevel=LEVEL
107             Set log level to one of the following, default notice:
108
109                   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

CONFIGURATION

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
121     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
124     Here are the different configuration settings:
125
126           default-route-distance <1-255>
127
128           default-route-metric <1-1024>
129
130           igmp-query-interval <1-65535>
131
132           igmp-querier-timeout <8-65535>
133
134           hello-interval <30-18724>
135
136           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
143           bsr-candidate [address | ifname] [priority <number>]
144
145           rp-candidate [address | ifname] [priority <0-255>] [time
146           <10-16384>]
147                 group-prefix <group>[/<masklen> | masklen <masklen>]
148                  ...
149                 group-prefix ...
150
151           rp-address <address> [<group-addr>[/<masklen> | masklen <masklen]
152
153           spt-threshold [rate <KBPS> | packets <NUM> | infinity] [interval
154           <SEC>]
155
156     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
161     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
173     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
182     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
186     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
199     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
206     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
244     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
249     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
256           ·  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
269           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
278           Multiple lines of group-prefix may be given, but max number of
279           records supported in pimd is 255.
280
281     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
287     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

SIGNALS

295     pimd responds to the following signals:
296
297     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
306     For convenience in sending signals, pimd writes its process ID to
307     /var/run/pimd.pid upon startup.
308

FILES

310     /etc/pimd.conf
311     /var/run/pimd/pimd.dump
312     /var/run/pimd.pid
313

SEE ALSO

315     mrouted(8), smcroute(8), /usr/share/doc/pimd/
316
317     PIM-SM is described in, the now obsolete RFC2362, and the current
318     RFC4601, with additions in RFC5059 and RFC5796.
319
320     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

AUTHORS

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
329     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.
332
333BSD                               Mar 3, 2016                              BSD
Impressum