Provided by: pimd_2.3.2-4_amd64 bug

NAME

     pimd — 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):
       maintains the traditional IP multicast service model of receiver-initiated membership;
       uses explicit joins that propagate hop-by-hop from members' directly connected routers
        toward the distribution tree.
       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.
       is not dependent on a specific unicast routing protocol; and
       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 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:

           default-route-distance <1-255>

           default-route-metric <1-1024>

           igmp-query-interval <1-65535>

           igmp-querier-timeout <8-65535>

           hello-interval <30-18724>

           phyint <address | ifname>
                 [disable | enable] [igmpv2 | igmpv3]
                 [dr-priority <1-4294967294>]
                 [ttl-threshold <1-255>] [distance <1-255>] [metric <1-1024>]
                 [altnet <network> [/<masklen> | masklen <masklen>]]
                 [scoped <network> [/<masklen> | masklen <masklen>]]

           bsr-candidate [address | ifname] [priority <number>]

           rp-candidate [address | ifname] [priority <0-255>] [time <10-16384>]
                 group-prefix <group>[/<masklen> | masklen <masklen>]
                  ...
                 group-prefix ...

           rp-address <address> [<group-addr>[/<masklen> | masklen <masklen]

           spt-threshold [rate <KBPS> | packets <NUM> | infinity] [interval <SEC>]

     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:
             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.
             igmpv2: Force interface to use IGMPv2, or
             igmpv3: Use IGMPv3, this is the default since v2.3.0.
             dr-priority <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 all PIM routers on
              the same LAN the highest priority router wins the DR election, regardless of its
              IP.  If any router does 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.
             ttl-threshold <1-255>: The TTL threshold for multicast frames to be forwarded from
              this interface.  Default: 1
             distance <1-255>: Use this to override the default-route-distance (101) on this
              phyint in PIM Assert elections.
             metric <1-1024>: The cost of sending data through this interface.  Defaults to
              default-route-metric (1024) if not assigned.
             altnet <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.
             scoped <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.

     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:

             address | ifname: Optional local IPv4 address, or interface name to acquire address
              from.  If both address and ifname is left out, pimd will default to the highest
              active IP address.
             priority <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 pimd and Cisco IOS defaults to 0 for both, but the standard says 192 for RP.
             time <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.

           The group-prefix sub-setting to rp-candidate is the set of multicast groups that the
           CRP will advertise to other routers, if it wins an election:
                   group: A specific multicast group or network range this router will handle.
                   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.

           Multiple lines of group-prefix may be given, but max number of records supported in
           pimd is 255.

     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

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