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

NAME

     pimd -- PIM-SM v2 dynamic multicast routing daemon

SYNOPSIS

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

DESCRIPTION

     pimd is a lightweight stand-alone PIM-SM v2 multicast routing daemon.  This is the original USC (netweb/catarina) implementation of the pro-
     tocol, which nowadays is fully free to use under the 3-clause BSD license.

     Protocol Independent Multicast - Sparse Mode (PIM-SM):
     o	 maintains the traditional IP multicast service model of receiver-initiated membership;
     o	 uses explicit joins that propagate hop-by-hop from members' directly connected routers toward the distribution tree.
     o	 builds a shared multicast distribution tree centered at a Rendezvous Point, and then builds source-specific trees for those sources whose
	 data traffic warrants it.
     o	 is not dependent on a specific unicast routing protocol; and
     o	 uses soft-state mechanisms to adapt to underlying network conditions and group dynamics.

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

     pimd implements RFC 2362, which has been obsoleted by RFC 4601.  Please see the TODO file for more information on this.

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, instead of the default /etc/pimd.conf.

     -d, --debug[=LEVEL[,LEVEL...]
	     By default, pimd detaches from the invoking terminal.  If this option is specified, pimd it runs in foreground of the starting termi-
	     nal and responds to signals.  If -d is given with no argument, the debug level defaults to igmp, cache, interface, groups, prunes,
	     routes and peers.

	     Regardless of the debug level, pimd always writes warning and error messages to the system log daemon.  Debug levels have the follow-
	     ing effects:

		   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, or 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 foreground, do not detach from calling terminal

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

     -N, --disable-vifs
	     This prevents pimd from being activated on all interfaces by default.  Use `phyint enable` to selectively activate it.

     -q, --quit-daemon
	     Tell a running pimd to quit.  Similar to --reload-config but this command sends SIGTERM.

     -r, --show-routes
	     Show state of VIFs and multicast routing tables. This is command sends SIGUSR1 to a running pimd, similar to --reload-config.

     -v, --version
	     Show pimd version

CONFIGURATION

     The configuration is kept in the file /etc/pimd.conf.  The file format is free-form: whitespace (including newlines) is not significant.
     There are eight different types of configuration commands:

	   default_source_preference <preference>

	   default_source_metric <metric>

	   phyint <local-addr|ifname> [disable|enable]
	   [altnet <network> masklen <masklen>]
	   [scoped <network> masklen <masklen>]
	   [threshold thr] [preference pref] [metric cost]

	   cand_rp [<local-addr>] [priority <number>] [time <number>]

	   cand_bootstrap_router [<local-addr>] [priority <number>]

	   rp_address <rp-addr> [<group-addr> [masklen <masklen] [priority <number>]]

	   group_prefix <group-addr> [masklen <masklen>] [priority <number>]

	   switch_data_threshold [rate <number> interval <number>]

	   switch_register_threshold [rate <number> interval <number>]

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

     The default_source_preference option is used by assert elections to determine upstream routers.  Currently pimd cannot reliably obtain pref-
     erences and metrics from the unicast routing protocols, so a default preference may be configured.  In an assert election, the router adver-
     tising 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 prefered over poor-little pimd.

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

     The phyint option refers to a physical interface and must come after default_source_metric.  Select the interface either by its IP address
     local-addr or interface name ifname (e.g. le0).  If you just want to activate this interface with default values, you don't need to put any-
     thing else on the line.  However, there are some additional settings:
     o	 disable.  Do not send PIM-SM traffic through this interface nor listen for PIM-SM traffic from this interface.  Default: enable.  enable.
	 Selectively enable which interfaces to send PIM-SM traffic through.  Useful with the -N command line option.
     o	 preference pref.  This interface's value in an election. It will have the pimd default_source_preference if not assigned.
     o	 metric cost.  The cost of sending data through this interface. It will have the default_source_metric if not assigned.

     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.

     The cand_rp setting refers to Candidate Rendez-vous Point (CRP).  It specifies which interface on this machine should be included in RP elec-
     tions.
     o	 local-addr.  The default is the highest active IP address.
     o	 time number.  The number of seconds to wait between advertising this CRP. The default value is 60 seconds.
     o	 priority number.  How important this CRP is compared to others. The lower the value here, the more important the CRP.

     The cand_bootstrap_router setting is similar to CRP.  Only difference is the lack of a time option.

     The group_prefix statement outlines the set of multicast addresses that the CRP, if it wins an election, will advertise to other routers.
     o	 group-addr.  A specific multicast group or network range this router will handle.
     o	 masklen len.  The number of IP address segments taken up by the netmask. Remember that a multicast address is a Class D and has a netmask
	 of 240.0.0.0, which means its length is 4.

     Max group_prefix multicast addresses supported in pimd is 255.

     The rp_address setting is for static Rendez-vous Point configurations.  The argument can either be a unicast address or a multicast group,
     with an optional group address, mask length, and priority arguments.

     The switch_data_threshold setting defines the threshold at which transmission rates trigger the changeover from the shared tree to the RP
     tree; starting the line with switch_register_threshold does the opposite in the same format.  Regardless of which of these you choose, the
     rate option is for transmission rate in bits per second, interval is the sample rate in seconds -- with a recommended minimum of five sec-
     onds.  It is recommended to have the same interval if both settings are used.

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 --show-routes option above.

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

FILES

     /etc/pimd.conf
     /var/run/pimd/pimd.dump
     /var/run/pimd.pid

SEE ALSO

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

     PIM-SM is described in, the now obsolete RFC 2362, and the current RFC 4601, with additions in RFC 5059 and RFC 5796.

     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.  With contributions by many others.

     This manual page was initially written by Antonin Kral for the Debian GNU/Linux system, and then updated by Joachim Nilsson for the GitHub
     pimd project.

BSD
								   Aug 22, 2010 							       BSD