Annotation of embedaddon/pimd/pimd.8, revision 1.1
1.1 ! misho 1: .\" Hey, EMACS: -*- nroff -*-
! 2: .\" First parameter, NAME, should be all caps
! 3: .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
! 4: .\" other parameters are allowed: see man(7), man(1)
! 5: .Dd Mar 3, 2016
! 6: .\" Please adjust this date whenever revising the manpage.
! 7: .Dt PIMD 8 SMM
! 8: .Os
! 9: .Sh NAME
! 10: .Nm pimd
! 11: .Nd PIM-SM/SSM v2 dynamic multicast routing daemon
! 12: .Sh SYNOPSIS
! 13: .Nm pimd
! 14: .Op Fl fhlNqr
! 15: .Op Fl c Ar FILE
! 16: .Op Fl d Ar [SYS[,SYS,...]
! 17: .Op Fl s Ar LEVEL
! 18: .Sh DESCRIPTION
! 19: .Nm
! 20: is a lightweight, stand-alone PIM-SM/SSM v2 multicast routing daemon
! 21: available under the free 3-clause BSD license. This is the restored
! 22: original from University of Southern California, by Ahmed Helmy, Rusty
! 23: Eddy and Pavlin Ivanov Radoslavov.
! 24: .Pp
! 25: Protocol Independent Multicast - Sparse Mode (PIM-SM):
! 26: .Bl -bullet -width 1n -compact
! 27: .It
! 28: maintains the traditional IP multicast service model of
! 29: receiver-initiated membership;
! 30: .It
! 31: uses explicit joins that propagate hop-by-hop from members' directly
! 32: connected routers toward the distribution tree.
! 33: .It
! 34: builds a shared multicast distribution tree centered at a Rendezvous
! 35: Point (RP), and then builds source-specific trees for those sources
! 36: whose data traffic warrants it.
! 37: .It
! 38: is not dependent on a specific unicast routing protocol; and
! 39: .It
! 40: uses soft-state mechanisms to adapt to underlying network conditions and
! 41: group dynamics.
! 42: .El
! 43: .Pp
! 44: The robustness, flexibility, and scaling properties of this architecture
! 45: make it well suited to large heterogeneous internetworks.
! 46: .Pp
! 47: .Nm
! 48: originally only implemented RFC2362, but since v2.3.0 is supporting more
! 49: and more of RFC4601.
! 50: .Sh OPTIONS
! 51: This program follows the usual UNIX command line syntax, with long
! 52: options starting with two dashes (`-'). The options are as follows:
! 53: .Bl -tag -width Ds
! 54: .It Fl h, -help
! 55: Print a help message and exit.
! 56: .It Fl c, -config=FILE
! 57: Specify an alternative configuration file, default
! 58: .Pa /etc/pimd.conf .
! 59: If
! 60: .Nm
! 61: cannot find its configuration file it will start up with fallback
! 62: defaults, which include enabling both
! 63: .Cm bsr-candidate
! 64: and
! 65: .Cm rp-candidate .
! 66: .It Fl d, -debug[=SYS[,SYS...]
! 67: By default,
! 68: .Nm
! 69: daemonizes itself by detaching from the invoking terminal and forking to
! 70: the background. However, if
! 71: .Fl d, -debug
! 72: or
! 73: .Fl f, -foreground
! 74: is specified,
! 75: .Nm
! 76: runs in the foreground of the starting terminal. If
! 77: .Fl d
! 78: is given without any argument
! 79: .Nm
! 80: defaults to debug all subystems.
! 81: .Pp
! 82: Available subsystems are:
! 83: .Pp
! 84: .Bl -tag -width pim_routes -compact -offset indent
! 85: .It Cm packet
! 86: Debug inbound/outbout packets
! 87: .It Cm prunes
! 88: Pruning operations, or pruned routes
! 89: .It Cm routes
! 90: Routing messages
! 91: .It Cm rtdetail
! 92: Detailed routing information
! 93: .It Cm peers
! 94: Neighbor gossip
! 95: .It Cm cache
! 96: Debug routing cache
! 97: .It Cm timeout
! 98: Debug timeouts
! 99: .It Cm interface
! 100: Show interface (VIF) debug messages
! 101: .It Cm groups
! 102: Debug group memberships
! 103: .It Cm mtrace
! 104: Multicast traceroute information
! 105: .It Cm igmp
! 106: Debug IGMP messages
! 107: .It Cm icmp
! 108: Debug ICMP messages
! 109: .It Cm rsrr
! 110: Debug RSRR messages
! 111: .It Cm pim
! 112: All PIM messages
! 113: .It Cm pim_routes
! 114: PIM routing messages
! 115: .It Cm pim_bsr
! 116: PIM bootstrap router messages
! 117: .It Cm pim_detail
! 118: Detailed PIM debug
! 119: .It Cm pim_hello
! 120: Debug hello messages to/from neighbors
! 121: .El
! 122: .It Fl f, -foreground
! 123: Run in the foreground, do not detach from calling terminal and do not
! 124: fork to background. Useful not only when debugging (above) but also
! 125: when running under a process monitor like daemontools, runit, finit, or
! 126: systemd.
! 127: .It Fl l, -reload-config
! 128: Tell a running pimd to reload its configuration. This is done by sending
! 129: a SIGHUP to the PID listed in
! 130: .Pa /var/run/pimd.pid .
! 131: Depending on the capabilities of your user, you may need to be root to
! 132: do this.
! 133: .It Fl N, -disable-vifs
! 134: This prevents
! 135: .Nm
! 136: from being activated on all interfaces by default. When this command
! 137: line option is given, use `phyint IFNAME enable` to selectively activate
! 138: PIM services on an interface.
! 139: .It Fl q, -quit-daemon
! 140: Tell a running
! 141: .Nm
! 142: to quit. Similar to
! 143: .Fl l, -reload-config
! 144: but this command sends SIGTERM. Depending on the capabilities of your
! 145: user, you may need to be root to do this.
! 146: .It Fl r, -show-routes
! 147: Show state of VIFs and multicast routing tables. This is command sends
! 148: SIGUSR1 to a running
! 149: .Nm ,
! 150: similar to
! 151: .Fl l -reload-config.
! 152: Depending on the capabilities of your user, you may need to be root to
! 153: do this.
! 154: .It Fl v, -version
! 155: Show
! 156: .Nm
! 157: version
! 158: .It Fl s, -loglevel=LEVEL
! 159: Set log level to one of the following, default
! 160: .Nm notice :
! 161: .Pp
! 162: .Bl -tag -width WARNING -compact -offset indent
! 163: .It Cm none
! 164: Disable all logging
! 165: .It Cm error
! 166: Error conditions
! 167: .It Cm warning
! 168: Warning conditions
! 169: .It Cm notice
! 170: Normal but significant condition (Default)
! 171: .It Cm info
! 172: Informational
! 173: .It Cm debug
! 174: Debug-level messages
! 175: .El
! 176: .El
! 177: .Sh CONFIGURATION
! 178: The configuration is kept in the file
! 179: .Pa /etc/pimd.conf .
! 180: The file format is relatively free-form: whitespace (including newlines) is not
! 181: significant. However, the order of some statements are important, see
! 182: more below.
! 183: .Pp
! 184: All <masklen> arguments to an IPv4 address, group or network can also be
! 185: given in the alternative /CIDR format. E.g., <group>/<masklen>.
! 186: .Pp
! 187: Here are the different configuration settings:
! 188: .Bl -item -offset indent
! 189: .It
! 190: .Cm default-route-distance
! 191: .Ar <1-255>
! 192: .It
! 193: .Cm default-route-metric
! 194: .Ar <1-1024>
! 195: .It
! 196: .Cm igmp-query-interval
! 197: .Ar <1-65535>
! 198: .It
! 199: .Cm igmp-querier-timeout
! 200: .Ar <8-65535>
! 201: .It
! 202: .Cm hello-interval
! 203: .Ar <30-18724>
! 204: .It
! 205: .Cm phyint
! 206: .Cm <address | ifname>
! 207: .Bl -item -offset indent
! 208: .Op Cm disable | enable
! 209: .Op Cm igmpv2 | igmpv3
! 210: .br
! 211: .Op Cm dr-priority Ar <1-4294967294>
! 212: .br
! 213: .Op Cm ttl-threshold Ar <1-255>
! 214: .Op Cm distance Ar <1-255>
! 215: .Op Cm metric Ar <1-1024>
! 216: .br
! 217: .Oo
! 218: .Cm altnet Ar <network> Op Cm /<masklen> | Cm masklen <masklen>
! 219: .Oc
! 220: .br
! 221: .Oo
! 222: .Cm scoped Ar <network> Op Cm /<masklen> | Cm masklen <masklen>
! 223: .Oc
! 224: .El
! 225: .It
! 226: .Cm bsr-candidate
! 227: .Op Ar address | Ar ifname
! 228: .Op Cm priority Ar <number>
! 229: .It
! 230: .Cm rp-candidate
! 231: .Op Ar address | Ar ifname
! 232: .Op Cm priority Ar <0-255>
! 233: .Op Cm time Ar <10-16384>
! 234: .Bl -item -offset indent -compact
! 235: .It
! 236: .Cm group-prefix Ar <group>[/<masklen> | Cm masklen Ar <masklen>]
! 237: .It
! 238: ...
! 239: .It
! 240: .Cm group-prefix ...
! 241: .El
! 242: .It
! 243: .Cm rp-address Ar <address> [<group-addr>[/<masklen> | masklen <masklen]
! 244: .It
! 245: .Cm spt-threshold
! 246: .Op Cm rate Ar <KBPS> | Cm packets Ar <NUM> | Cm infinity
! 247: .Op Cm interval Ar <SEC>
! 248: .El
! 249: .Pp
! 250: By default,
! 251: .Nm
! 252: will be activated on all multicast capable interfaces. The
! 253: .Cm phyint
! 254: setting and the
! 255: .Fl N, -disable-vifs
! 256: command line option control this behaviour. More on the
! 257: .Cm phyint
! 258: interface configuration setting below.
! 259: .Pp
! 260: The
! 261: .Cm default-route-distance
! 262: option has nothing to do with the system default route, it is rather the
! 263: default value for the unicast routing protocol's administrative
! 264: distance. It is used in PIM Assert elections to determine upstream
! 265: routers. Currently
! 266: .Nm
! 267: cannot obtain the admin distance and metric from the unicast routing
! 268: protocols, so a default routing protocol distance (the RFC confusingly
! 269: refers to this as
! 270: .Em metric prefererence )
! 271: may be configured. In a PIM Assert election, the router advertising the
! 272: lowest assert preference will be selected as the forwarder and upstream
! 273: router for the LAN. Setting 101 should be sufficiently high so that
! 274: asserts from Cisco or GateD routers are preferred over poor-little pimd.
! 275: .Pp
! 276: It is reccommended that distances be set such that metrics are never
! 277: consulted. However, default routing metrics may also be set using the
! 278: .Cm default-route-metric
! 279: option. (Again, this has nothing to do with the system default route.)
! 280: This item sets the cost for sending data through this router. You want
! 281: only PIM-SM data to go to this daemon; so once again, a high value is
! 282: recommended to prevent accidental usage. The preferred default value is
! 283: 1024. Both defaults can be overridden per phyint, so learned routes, or
! 284: PIM Asserts use the phyint's values.
! 285: .Pp
! 286: Please also note that PIM Assert elections are not the same as the DR
! 287: election. The PIM Assert election determines the active multicast
! 288: forwarder, whereas the DR election determines the active PIM router.
! 289: .Pp
! 290: Two settings for IGMP behavior are available:
! 291: .Cm igmp-query-interval
! 292: and
! 293: .Cm igmp-querier-timeout
! 294: which are similar, but very different. The former controls the interval
! 295: between IGMP querys when elected as querier, the latter controls the
! 296: timeout for the elected querier -- before
! 297: .Nm pimd
! 298: decides to take over. In IGMP the lowest numerical address in a LAN
! 299: becomes the elected querier. Obviously these settings must be handled
! 300: with care. The RFC recommends that the querier timeout is set to a
! 301: robustness value times the query interval, plus have the query response
! 302: time. The pimd robustness value for IGMP is 3 and the default query
! 303: response time is 10 sec. Since pimd v2.3.0 the default query interval
! 304: is 12 sec, which makes the querier timeut default to 41 sec, but this is
! 305: rounded off to 42 to honor the late Douglas Adams.
! 306: .Pp
! 307: The PIM Hello message interval can be tuned by changing the
! 308: .Cm hello-interval
! 309: setting. Changing this value also affects the hold-time value included
! 310: in Hello messages. The hold-time value is 3.5 times hello-interval.
! 311: The default value for the Hello interval is 30 sec. Anything less than
! 312: 30 sec is considered an "aggressive" setting and is unsupported.
! 313: .Pp
! 314: The
! 315: .Nm phyint
! 316: option refers to a physical interface and must come after
! 317: .Cm default-route-metric
! 318: and
! 319: .Cm default-route-distance .
! 320: Select the interface either by its IP
! 321: .Ar address
! 322: or interface name
! 323: .Ar ifname
! 324: (e.g. eth0). If you just want to activate this interface with default
! 325: values, you don't need to put anything else on the line. However, there
! 326: are some additional settings:
! 327: .Bl -bullet -offset indent -width 1n -compact
! 328: .It
! 329: .Nm disable :
! 330: Do not send PIM-SM traffic through this interface nor listen for PIM-SM traffic
! 331: from this interface. Default: enable.
! 332: .Nm enable :
! 333: Selectively enable which interfaces to send PIM-SM traffic through. Useful with
! 334: the
! 335: .Fl N
! 336: command line option.
! 337: .It
! 338: .Nm igmpv2 :
! 339: Force interface to use IGMPv2, or
! 340: .It
! 341: .Nm igmpv3 :
! 342: Use IGMPv3, this is the default since v2.3.0.
! 343: .It
! 344: .Cm dr-priority Ar <1-4294967294> :
! 345: When there are multiple PIM routers on the same LAN the DR is usually
! 346: elected based on the highest numerical IP address. This setting can be
! 347: used to control the DR Priority option in PIM Hellow messages, which by
! 348: default otherwise is 1. When the DR Priority option is advertised by
! 349: .Em all
! 350: PIM routers on the same LAN the highest priority router wins the DR
! 351: election, regardless of its IP. If any router does
! 352: .Em not
! 353: advertise the DR Priority option, or the same priority is advertised by
! 354: more than one router, the protocol falls back to using the IP address.
! 355: .It
! 356: .Cm ttl-threshold Ar <1-255> :
! 357: The TTL threshold for multicast frames to be forwarded from this
! 358: interface. Default: 1
! 359: .It
! 360: .Cm distance Ar <1-255> :
! 361: Use this to override the
! 362: .Nm default-route-distance
! 363: (101) on this
! 364: .Nm phyint
! 365: in PIM Assert elections.
! 366: .It
! 367: .Cm metric Ar <1-1024> :
! 368: The cost of sending data through this interface. Defaults to
! 369: .Nm default-route-metric
! 370: (1024) if not assigned.
! 371: .It
! 372: .Cm altnet Ar <network/len> :
! 373: Alternative host(s)/network(s) to accept as locally attached multicast
! 374: sources on a given interface. If a phyint is attached to multiple IP
! 375: subnets, describe each additional subnet with the altnet keyword.
! 376: .It
! 377: .Cm scoped Ar <network/len> :
! 378: Optional scoping of multicast groups. This allows interfaces to be
! 379: configured as an administrative boundary for the specified
! 380: group(s). Multicast streams belonging to the scoped groups will not be
! 381: forwarded.
! 382: .El
! 383: .Pp
! 384: Add one
! 385: .Nm phyint
! 386: line per interface on this router. If you don't do this,
! 387: .Nm pimd
! 388: will either be completely silent (if you provide the
! 389: .Fl N
! 390: command line option), or simply assume that you want it to utilize all interfaces
! 391: using default settings.
! 392: .Pp
! 393: Both the
! 394: .Cm bsr-candidate
! 395: (CBSR) and
! 396: .Cm rp-candidate
! 397: (CRP) settings are enabled in the default configuration. Disabling
! 398: them, by commenting them out in the config file, for all PIM capable
! 399: routers is a bad idea. When troubleshooting, ensure at least one
! 400: bootstrap router (BSR) and at least one rendez-vous point (RP) in
! 401: PIM-SM, is available. Both settings share the following options, with
! 402: priority being interpreted differently:
! 403: .Pp
! 404: .Bl -bullet -offset indent -width 1n -compact
! 405: .It
! 406: .Nm address | ifname :
! 407: Optional local IPv4 address, or interface name to acquire address from.
! 408: If both address and ifname is left out,
! 409: .Nm
! 410: will default to the highest active IP address.
! 411: .It
! 412: .Nm priority Ar <0-255> :
! 413: How important this router is compared to others. For CRP, the lower the
! 414: value the more important the router is considered. For BSR it is of
! 415: course the exact opposite: a higher value is preferred. If the priority
! 416: is left out
! 417: .Nm
! 418: and Cisco IOS defaults to 0 for both, but the standard says 192 for RP.
! 419: .It
! 420: .Nm time Ar <10-16383> :
! 421: The number of seconds to wait between advertising this CRP. The default
! 422: value is 30 seconds. Use a lower value for faster convergence.
! 423: .El
! 424: .Pp
! 425: .Bl -item -offset indent -compact
! 426: .It
! 427: The
! 428: .Nm group-prefix
! 429: sub-setting to
! 430: .Nm rp-candidate
! 431: is the set of multicast groups that the CRP will advertise to other
! 432: routers, if it wins an election:
! 433: .Bl -bullet -offset indent -width 1n -compact
! 434: .It
! 435: .Nm group :
! 436: A specific multicast group or network range this router will handle.
! 437: .It
! 438: .Nm masklen :
! 439: Optional number of groups, in prefix length format. Remember that a
! 440: multicast address is a Class D and has a netmask of 240.0.0.0, which
! 441: means its length is 4.
! 442: .El
! 443: .Pp
! 444: Multiple lines of
! 445: .Nm group-prefix
! 446: may be given, but max number of records supported in pimd is 255.
! 447: .El
! 448: .Pp
! 449: The
! 450: .Nm rp-address
! 451: setting is for static rendezvous point (RP) configurations. It defines
! 452: the RP for a given group, or range or groups. The argument can be
! 453: either a unicast address or a multicast group, with an optional group
! 454: address and netmask. Default group and netmask is 224.0.0.0/16.
! 455: .Nm Note:
! 456: all static RP's are announced with priority 1.
! 457: .Pp
! 458: The
! 459: .Nm spt-threshold
! 460: setting replaces two older configuration settings,
! 461: .Nm switch_data_threshold
! 462: and
! 463: .Nm switch_register_threshold .
! 464: It controls the switch-over from the shared tree to the shortest-path
! 465: source tree. The default is to do the switch-over after the first
! 466: packet, but only after 100 seconds. If
! 467: .Ar infinity
! 468: is specified the shortest path switch-over is disabled.
! 469: .Sh SIGNALS
! 470: .Nm
! 471: responds to the following signals:
! 472: .Pp
! 473: .Bl -tag -width TERM -compact
! 474: .It HUP
! 475: Restarts
! 476: .Nm .
! 477: The configuration file is reread every time this signal is evoked.
! 478: .It TERM
! 479: Terminates execution gracefully (i.e. by sending good-bye messages to all neighboring
! 480: routers).
! 481: .It INT
! 482: The same as TERM.
! 483: .It USR1
! 484: Dumps the internal state of VIFs and multicast routing tables to
! 485: .Pa /var/run/pimd/pimd.dump .
! 486: See also the
! 487: .Fl r, -show-routes
! 488: option above.
! 489: .\" Not implemented yet, still TODO
! 490: .\" .It USR2
! 491: .\" Dumps the internal cache tables to
! 492: .\" .Pa /var/run/pimd/pimd.cache .
! 493: .\" Also not implemented yet, TODO
! 494: .\" .It QUIT
! 495: .\" Dumps the internal routing tables to stderr (only if
! 496: .\" .Nm
! 497: .\" was invoked with a non-zero debug level).
! 498: .El
! 499: .Pp
! 500: For convenience in sending signals,
! 501: .Nm
! 502: writes its process ID to
! 503: .Pa /var/run/pimd.pid
! 504: upon startup.
! 505: .Sh FILES
! 506: .Bl -tag -width /var/run/pimd/pimd.cache -compact
! 507: .It Pa /etc/pimd.conf
! 508: .\" .It Pa /var/run/pimd/pimd.cache
! 509: .It Pa /var/run/pimd/pimd.dump
! 510: .It Pa /var/run/pimd.pid
! 511: .El
! 512: .Sh SEE ALSO
! 513: .Xr mrouted 8 ,
! 514: .Xr smcroute 8 ,
! 515: .Xr /usr/share/doc/pimd/
! 516: .Pp
! 517: PIM-SM is described in, the now obsolete RFC2362, and the current
! 518: RFC4601, with additions in RFC5059 and RFC5796.
! 519: .Pp
! 520: The pages at USC, http://netweb.usc.edu/pim/, are unfortunately no
! 521: longer available. The wiki pages at http://github.com/troglobit/pimd/,
! 522: the new GitHub project, are an attempt to gather as much info as
! 523: possible.
! 524: .Sh AUTHORS
! 525: .Nm
! 526: was written by Ahmed Helmy, George Edmond "Rusty" Eddy, and Pavlin
! 527: Ivanov Radoslavov. PIM-SSM, including full IGMPv3 support, added by
! 528: Markus Veranen. With contributions by many others.
! 529: .Pp
! 530: This manual page was initially written by Antonín Král for the Debian
! 531: GNU/Linux system, and then updated by Joachim Nilsson for the GitHub
! 532: pimd project.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pimd.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pimd