pimd - Man Page

PIM-SM/SSM v2 dynamic multicast routing daemon

Synopsis

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

Description

pimd 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.

Protocol Independent Multicast - Sparse Mode (PIM-SM):

The robustness, flexibility, and scaling properties of this architecture make it well suited to large heterogeneous internetworks.

pimd originally only implemented RFC2362, but since v2.3.0 is supporting more and more of RFC4601.

Options

This program follows the usual UNIX command line syntax, with long options starting with two dashes (`-'). The options are as follows:

-h, --help

Print a help message and exit.

-c, --config=FILE

Specify an alternative configuration file, default /etc/pimd.conf. If pimd cannot find its configuration file it will start up with fallback defaults, which include enabling both bsr-candidate and rp-candidate.

-d, --debug[=SYS[,SYS...]

By default, pimd daemonizes itself by detaching from the invoking terminal and forking to the background. However, if -d, --debug or -f, --foreground is specified, pimd runs in the foreground of the starting terminal. If -d is given without any argument pimd defaults to debug all subystems.

Available subsystems are:

packet

Debug inbound/outbout packets

prunes

Pruning operations, or pruned routes

routes

Routing messages

rtdetail

Detailed routing information

peers

Neighbor gossip

cache

Debug routing cache

timeout

Debug timeouts

interface

Show interface (VIF) debug messages

groups

Debug group memberships

mtrace

Multicast traceroute information

igmp

Debug IGMP messages

icmp

Debug ICMP messages

rsrr

Debug RSRR messages

pim

All PIM messages

pim_routes

PIM routing messages

pim_bsr

PIM bootstrap router messages

pim_detail

Detailed PIM debug

pim_hello

Debug hello messages to/from neighbors

-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.

-l, --reload-config

Tell a running pimd to reload its configuration. This is done by sending a SIGHUP to the PID listed in /var/run/pimd.pid. Depending on the capabilities of your user, you may need to be root to do this.

-N, --disable-vifs

This prevents pimd 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.

-q, --quit-daemon

Tell a running pimd to quit. Similar to -l, --reload-config but this command sends SIGTERM. Depending on the capabilities of your user, you may need to be root to do this.

-r, --show-routes

Show state of VIFs and multicast routing tables. This is command sends SIGUSR1 to a running pimd, similar to -l --reload-config. Depending on the capabilities of your user, you may need to be root to do this.

-v, --version

Show pimd version

-s, --loglevel=LEVEL

Set log level to one of the following, default notice:

none

Disable all logging

error

Error conditions

warning

Warning conditions

notice

Normal but significant condition (Default)

info

Informational

debug

Debug-level messages

Configuration

The configuration is kept in the file /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.

All <masklen> arguments to an IPv4 address, group or network can also be given in the alternative /CIDR format. E.g., <group>/<masklen>.

Here are the different configuration settings:

By default, pimd will be activated on all multicast capable interfaces. The phyint setting and the -N, --disable-vifs command line option control this behaviour. More on the phyint interface configuration setting below.

The 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 pimd 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 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.

It is reccommended that distances be set such that metrics are never consulted. However, default routing metrics may also be set using the 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.

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.

Two settings for IGMP behavior are available: igmp-query-interval and 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 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.

The PIM Hello message interval can be tuned by changing the 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.

The phyint option refers to a physical interface and must come after default-route-metric and default-route-distance. Select the interface either by its IP address or interface name 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:

Add one phyint line per interface on this router. If you don't do this, pimd will either be completely silent (if you provide the -N command line option), or simply assume that you want it to utilize all interfaces using default settings.

Both the bsr-candidate (CBSR) and 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:

The 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. Note: all static RP's are announced with priority 1.

The spt-threshold setting replaces two older configuration settings, switch_data_threshold and 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 infinity is specified the shortest path switch-over is disabled.

Signals

pimd responds to the following signals:

HUP

Restarts pimd. The configuration file is reread every time this signal is evoked.

TERM

Terminates execution gracefully (i.e. by sending good-bye messages to all neighboring routers).

INT

The same as TERM.

USR1

Dumps the internal state of VIFs and multicast routing tables to /var/run/pimd/pimd.dump. See also the -r, --show-routes option above.

For convenience in sending signals, pimd writes its process ID to /var/run/pimd.pid upon startup.

Files

See Also

mrouted(8), smcroute(8), /usr/share/doc/pimd/

PIM-SM is described in, the now obsolete RFC2362, and the current RFC4601, with additions in RFC5059 and RFC5796.

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.

Authors

pimd 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.

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.

Info

March 3, 2016