pimd.8

.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.Dd Mar 3, 2016
.\" Please adjust this date whenever revising the manpage.
.Dt PIMD 8 SMM
.Os
.Sh NAME
.Nm pimd
.Nd PIM-SM/SSM v2 dynamic multicast routing daemon
.Sh SYNOPSIS
.Nm pimd
.Op Fl fhlNqr
.Op Fl c Ar FILE
.Op Fl d Ar [SYS[,SYS,...]
.Op Fl s Ar LEVEL
.Sh DESCRIPTION
.Nm
is a lightweight, stand-alone PIM-SM/SSM v2 multicast routing daemon
available under the free 3-clause BSD license.  This is the restored
original from University of Southern California, by Ahmed Helmy, Rusty
Eddy and Pavlin Ivanov Radoslavov.
.Pp
Protocol Independent Multicast - Sparse Mode (PIM-SM):
.Bl -bullet -width 1n -compact
.It
maintains the traditional IP multicast service model of
receiver-initiated membership;
.It
uses explicit joins that propagate hop-by-hop from members' directly
connected routers toward the distribution tree.
.It
builds a shared multicast distribution tree centered at a Rendezvous
Point (RP), and then builds source-specific trees for those sources
whose data traffic warrants it.
.It
is not dependent on a specific unicast routing protocol; and
.It
uses soft-state mechanisms to adapt to underlying network conditions and
group dynamics.
.El
.Pp
The robustness, flexibility, and scaling properties of this architecture
make it well suited to large heterogeneous internetworks.
.Pp
.Nm
originally only implemented RFC2362, but since v2.3.0 is supporting more
and more of RFC4601.
.Sh OPTIONS
This program follows the usual UNIX command line syntax, with long
options starting with two dashes (`-').  The options are as follows:
.Bl -tag -width Ds
.It Fl h, -help
Print a help message and exit.
.It Fl c, -config=FILE
Specify an alternative configuration file, default
.Pa /etc/pimd.conf .
If
.Nm
cannot find its configuration file it will start up with fallback
defaults, which include enabling both
.Cm bsr-candidate
and
.Cm rp-candidate .
.It Fl d, -debug[=SYS[,SYS...]
By default,
.Nm
daemonizes itself by detaching from the invoking terminal and forking to
the background.  However, if
.Fl d, -debug
or
.Fl f, -foreground
is specified,
.Nm
runs in the foreground of the starting terminal.  If
.Fl d
is given without any argument
.Nm
defaults to debug all subystems.
.Pp
Available subsystems are:
.Pp
.Bl -tag -width pim_routes -compact -offset indent
.It Cm packet
Debug inbound/outbout packets
.It Cm prunes
Pruning operations, or pruned routes
.It Cm routes
Routing messages
.It Cm rtdetail
Detailed routing information
.It Cm peers
Neighbor gossip
.It Cm cache
Debug routing cache
.It Cm timeout
Debug timeouts
.It Cm interface
Show interface (VIF) debug messages
.It Cm groups
Debug group memberships
.It Cm mtrace
Multicast traceroute information
.It Cm igmp
Debug IGMP messages
.It Cm icmp
Debug ICMP messages
.It Cm rsrr
Debug RSRR messages
.It Cm pim
All PIM messages
.It Cm pim_routes
PIM routing messages
.It Cm pim_bsr
PIM bootstrap router messages
.It Cm pim_detail
Detailed PIM debug
.It Cm pim_hello
Debug hello messages to/from neighbors
.El
.It Fl f, -foreground
Run in the foreground, do not detach from calling terminal and do not
fork to background.  Useful not only when debugging (above) but also
when running under a process monitor like daemontools, runit, finit, or
systemd.
.It Fl l, -reload-config
Tell a running pimd to reload its configuration.  This is done by sending
a SIGHUP to the PID listed in
.Pa /var/run/pimd.pid .
Depending on the capabilities of your user, you may need to be root to
do this.
.It Fl N, -disable-vifs
This prevents
.Nm
from being activated on all interfaces by default.  When this command
line option is given, use `phyint IFNAME enable` to selectively activate
PIM services on an interface.
.It Fl q, -quit-daemon
Tell a running
.Nm
to quit.  Similar to
.Fl l, -reload-config
but this command sends SIGTERM.  Depending on the capabilities of your
user, you may need to be root to do this.
.It Fl r, -show-routes
Show state of VIFs and multicast routing tables. This is command sends
SIGUSR1 to a running
.Nm ,
similar to
.Fl l -reload-config.
Depending on the capabilities of your user, you may need to be root to
do this.
.It Fl v, -version
Show
.Nm
version
.It Fl s, -loglevel=LEVEL
Set log level to one of the following, default
.Nm notice :
.Pp
.Bl -tag -width WARNING -compact -offset indent
.It Cm none
Disable all logging
.It Cm error
Error conditions
.It Cm warning
Warning conditions
.It Cm notice
Normal but significant condition (Default)
.It Cm info
Informational
.It Cm debug
Debug-level messages
.El
.El
.Sh CONFIGURATION
The configuration is kept in the file
.Pa /etc/pimd.conf .
The file format is relatively free-form: whitespace (including newlines) is not
significant.  However, the order of some statements are important, see
more below.
.Pp
All <masklen> arguments to an IPv4 address, group or network can also be
given in the alternative /CIDR format.  E.g., <group>/<masklen>.
.Pp
Here are the different configuration settings:
.Bl -item -offset indent
.It
.Cm default-route-distance
.Ar <1-255>
.It
.Cm default-route-metric
.Ar <1-1024>
.It
.Cm igmp-query-interval
.Ar <1-65535>
.It
.Cm igmp-querier-timeout
.Ar <8-65535>
.It
.Cm hello-interval
.Ar <30-18724>
.It
.Cm phyint
.Cm <address | ifname>
.Bl -item -offset indent
.Op Cm disable | enable
.Op Cm igmpv2 | igmpv3
.br
.Op Cm dr-priority Ar <1-4294967294>
.br
.Op Cm ttl-threshold Ar <1-255>
.Op Cm distance Ar <1-255>
.Op Cm metric Ar <1-1024>
.br
.Oo
.Cm altnet Ar <network> Op Cm /<masklen> | Cm masklen <masklen>
.Oc
.br
.Oo
.Cm scoped Ar <network> Op Cm /<masklen> | Cm masklen <masklen>
.Oc
.El
.It
.Cm bsr-candidate
.Op Ar address | Ar ifname
.Op Cm priority Ar <number>
.It
.Cm rp-candidate
.Op Ar address | Ar ifname
.Op Cm priority Ar <0-255>
.Op Cm time Ar <10-16384>
.Bl -item -offset indent -compact
.It
.Cm group-prefix Ar <group>[/<masklen> | Cm masklen Ar <masklen>]
.It
 ...
.It
.Cm group-prefix ...
.El
.It
.Cm rp-address Ar <address> [<group-addr>[/<masklen> | masklen <masklen]
.It
.Cm spt-threshold
.Op Cm rate Ar <KBPS> | Cm packets Ar <NUM> | Cm infinity
.Op Cm interval Ar <SEC>
.El
.Pp
By default,
.Nm
will be activated on all multicast capable interfaces.  The
.Cm phyint
setting and the
.Fl N, -disable-vifs
command line option control this behaviour.  More on the
.Cm phyint
interface configuration setting below.
.Pp
The
.Cm default-route-distance
option has nothing to do with the system default route, it is rather the
default value for the unicast routing protocol's administrative
distance.  It is used in PIM Assert elections to determine upstream
routers.  Currently
.Nm
cannot obtain the admin distance and metric from the unicast routing
protocols, so a default routing protocol distance (the RFC confusingly
refers to this as
.Em metric prefererence )
may be configured.  In a PIM Assert election, the router advertising the
lowest assert preference will be selected as the forwarder and upstream
router for the LAN.  Setting 101 should be sufficiently high so that
asserts from Cisco or GateD routers are preferred over poor-little pimd.
.Pp
It is reccommended that distances be set such that metrics are never
consulted.  However, default routing metrics may also be set using the
.Cm default-route-metric
option.  (Again, this has nothing to do with the system default route.)
This item sets the cost for sending data through this router.  You want
only PIM-SM data to go to this daemon; so once again, a high value is
recommended to prevent accidental usage.  The preferred default value is
1024.  Both defaults can be overridden per phyint, so learned routes, or
PIM Asserts use the phyint's values.
.Pp
Please also note that PIM Assert elections are not the same as the DR
election.  The PIM Assert election determines the active multicast
forwarder, whereas the DR election determines the active PIM router.
.Pp
Two settings for IGMP behavior are available:
.Cm igmp-query-interval
and
.Cm igmp-querier-timeout
which are similar, but very different.  The former controls the interval
between IGMP querys when elected as querier, the latter controls the
timeout for the elected querier -- before
.Nm pimd
decides to take over.  In IGMP the lowest numerical address in a LAN
becomes the elected querier.  Obviously these settings must be handled
with care.  The RFC recommends that the querier timeout is set to a
robustness value times the query interval, plus have the query response
time.  The pimd robustness value for IGMP is 3 and the default query
response time is 10 sec.  Since pimd v2.3.0 the default query interval
is 12 sec, which makes the querier timeut default to 41 sec, but this is
rounded off to 42 to honor the late Douglas Adams.
.Pp
The PIM Hello message interval can be tuned by changing the
.Cm hello-interval
setting.  Changing this value also affects the hold-time value included
in Hello messages.  The hold-time value is 3.5 times hello-interval.
The default value for the Hello interval is 30 sec.  Anything less than
30 sec is considered an "aggressive" setting and is unsupported.
.Pp
The
.Nm phyint
option refers to a physical interface and must come after
.Cm default-route-metric
and
.Cm default-route-distance .
Select the interface either by its IP
.Ar address
or interface name
.Ar ifname
(e.g. eth0).  If you just want to activate this interface with default
values, you don't need to put anything else on the line.  However, there
are some additional settings:
.Bl -bullet -offset indent -width 1n -compact
.It
.Nm disable :
Do not send PIM-SM traffic through this interface nor listen for PIM-SM traffic
from this interface.  Default: enable.
.Nm enable :
Selectively enable which interfaces to send PIM-SM traffic through.  Useful with
the
.Fl N
command line option.
.It
.Nm igmpv2 :
Force interface to use IGMPv2, or
.It
.Nm igmpv3 :
Use IGMPv3, this is the default since v2.3.0.
.It
.Cm dr-priority Ar <1-4294967294> :
When there are multiple PIM routers on the same LAN the DR is usually
elected based on the highest numerical IP address.  This setting can be
used to control the DR Priority option in PIM Hellow messages, which by
default otherwise is 1.  When the DR Priority option is advertised by
.Em all
PIM routers on the same LAN the highest priority router wins the DR
election, regardless of its IP.  If any router does
.Em not
advertise the DR Priority option, or the same priority is advertised by
more than one router, the protocol falls back to using the IP address.
.It
.Cm ttl-threshold Ar <1-255> :
The TTL threshold for multicast frames to be forwarded from this
interface.  Default: 1
.It
.Cm distance Ar <1-255> :
Use this to override the
.Nm default-route-distance
(101) on this
.Nm phyint
in PIM Assert elections.
.It
.Cm metric Ar <1-1024> :
The cost of sending data through this interface.  Defaults to
.Nm default-route-metric
(1024) if not assigned.
.It
.Cm altnet Ar <network/len> :
Alternative host(s)/network(s) to accept as locally attached multicast
sources on a given interface. If a phyint is attached to multiple IP
subnets, describe each additional subnet with the altnet keyword.
.It
.Cm scoped Ar <network/len> :
Optional scoping of multicast groups. This allows interfaces to be
configured as an administrative boundary for the specified
group(s). Multicast streams belonging to the scoped groups will not be
forwarded.
.El
.Pp
Add one
.Nm phyint
line per interface on this router.  If you don't do this,
.Nm pimd
will either be completely silent (if you provide the
.Fl N
command line option), or simply assume that you want it to utilize all interfaces
using default settings.
.Pp
Both the
.Cm bsr-candidate
(CBSR) and
.Cm rp-candidate
(CRP) settings are enabled in the default configuration.  Disabling
them, by commenting them out in the config file, for all PIM capable
routers is a bad idea.  When troubleshooting, ensure at least one
bootstrap router (BSR) and at least one rendez-vous point (RP) in
PIM-SM, is available.  Both settings share the following options, with
priority being interpreted differently:
.Pp
.Bl -bullet -offset indent -width 1n -compact
.It
.Nm address | ifname :
Optional local IPv4 address, or interface name to acquire address from.
If both address and ifname is left out,
.Nm
will default to the highest active IP address.
.It
.Nm priority Ar <0-255> :
How important this router is compared to others.  For CRP, the lower the
value the more important the router is considered.  For BSR it is of
course the exact opposite: a higher value is preferred.  If the priority
is left out
.Nm
and Cisco IOS defaults to 0 for both, but the standard says 192 for RP.
.It
.Nm time Ar <10-16383> :
The number of seconds to wait between advertising this CRP.  The default
value is 30 seconds.  Use a lower value for faster convergence.
.El
.Pp
.Bl -item -offset indent -compact
.It
The
.Nm group-prefix
sub-setting to
.Nm rp-candidate
is the set of multicast groups that the CRP will advertise to other
routers, if it wins an election:
.Bl -bullet -offset indent -width 1n -compact
.It
.Nm group :
A specific multicast group or network range this router will handle.
.It
.Nm masklen :
Optional number of groups, in prefix length format. Remember that a
multicast address is a Class D and has a netmask of 240.0.0.0, which
means its length is 4.
.El
.Pp
Multiple lines of
.Nm group-prefix
may be given, but max number of records supported in pimd is 255.
.El
.Pp
The
.Nm rp-address
setting is for static rendezvous point (RP) configurations.  It defines
the RP for a given group, or range or groups.  The argument can be
either a unicast address or a multicast group, with an optional group
address and netmask.  Default group and netmask is 224.0.0.0/16.
.Nm Note:
all static RP's are announced with priority 1.
.Pp
The
.Nm spt-threshold
setting replaces two older configuration settings,
.Nm switch_data_threshold
and
.Nm switch_register_threshold .
It controls the switch-over from the shared tree to the shortest-path
source tree.  The default is to do the switch-over after the first
packet, but only after 100 seconds.  If
.Ar infinity
is specified the shortest path switch-over is disabled.
.Sh SIGNALS
.Nm
responds to the following signals:
.Pp
.Bl -tag -width TERM -compact
.It HUP
Restarts
.Nm .
The configuration file is reread every time this signal is evoked.
.It TERM
Terminates execution gracefully (i.e. by sending good-bye messages to all neighboring
routers).
.It INT
The same as TERM.
.It USR1
Dumps the internal state of VIFs and multicast routing tables to
.Pa /var/run/pimd/pimd.dump .
See also the
.Fl r, -show-routes
option above.
.\" Not implemented yet, still TODO
.\" .It USR2
.\" Dumps the internal cache tables to
.\" .Pa /var/run/pimd/pimd.cache .
.\" Also not implemented yet, TODO
.\" .It QUIT
.\" Dumps the internal routing tables to stderr (only if
.\" .Nm
.\" was invoked with a non-zero debug level).
.El
.Pp
For convenience in sending signals,
.Nm
writes its process ID to
.Pa /var/run/pimd.pid
upon startup.
.Sh FILES
.Bl -tag -width /var/run/pimd/pimd.cache -compact
.It Pa /etc/pimd.conf
.\" .It Pa /var/run/pimd/pimd.cache
.It Pa /var/run/pimd/pimd.dump
.It Pa /var/run/pimd.pid
.El
.Sh SEE ALSO
.Xr mrouted 8 ,
.Xr smcroute 8 ,
.Xr /usr/share/doc/pimd/
.Pp
PIM-SM is described in, the now obsolete RFC2362, and the current
RFC4601, with additions in RFC5059 and RFC5796.
.Pp
The pages at USC, http://netweb.usc.edu/pim/, are unfortunately no
longer available.  The wiki pages at http://github.com/troglobit/pimd/,
the new GitHub project, are an attempt to gather as much info as
possible.
.Sh AUTHORS
.Nm
was written by Ahmed Helmy, George Edmond "Rusty" Eddy, and Pavlin
Ivanov Radoslavov.  PIM-SSM, including full IGMPv3 support, added by
Markus Veranen.  With contributions by many others.
.Pp
This manual page was initially written by Antonín Král for the Debian
GNU/Linux system, and then updated by Joachim Nilsson for the GitHub
pimd project.