Annotation of embedaddon/pimd/README.md, revision 1.1
1.1 ! misho 1: README
! 2: ======
! 3: [![Travis Status][]][Travis] [![Coverity Status][]][Coverity Scan]
! 4:
! 5: Table of Contents
! 6: -----------------
! 7:
! 8: * [Introduction](#introduction)
! 9: * [Download](#download)
! 10: * [Building](#building)
! 11: * [Configuration](#configuration)
! 12: * [Example](#example)
! 13: * [Starting](#starting)
! 14: * [Monitoring](#monitoring)
! 15: * [Contributing](#contributing)
! 16:
! 17:
! 18: Introduction
! 19: ------------
! 20:
! 21: pimd is a lightweight, stand-alone PIM-SM/SSM multicast routing daemon
! 22: available under the free [3-clause BSD license][BSD license]. This is
! 23: the restored original version from University of Southern California, by
! 24: Ahmed Helmy, Rusty Eddy and Pavlin Ivanov Radoslavov.
! 25:
! 26: Today pimd is [maintained at GitHub][GitHub]. Use its facilities to
! 27: access the source, report bugs and feature requests, and send patches or
! 28: pull requests. Official release tarballs at [the homepage][homepage].
! 29:
! 30: pimd is primarily developed on Linux and should work as-is out of the
! 31: box on all major distributions. Other UNIX variants (OpenBSD, NetBSD,
! 32: and FreeBSD) should also work, but are not as thoroughly tested. For
! 33: some tips and details, see the `configure` script.
! 34:
! 35: For a summary of changes for each release, see the [ChangeLog][changes].
! 36:
! 37:
! 38: Download
! 39: --------
! 40:
! 41: Although the project makes heavy use of GitHub, it is *not* recommended
! 42: to use the ZIP file links GitHub provides. Instead, we recommend using
! 43: proper tarball releases from [the FTP][], or the [releases page][].
! 44:
! 45: The GitHub *Download ZIP* links, and ZIP files on the [releases page][],
! 46: do not include files from the GIT submodules. The configure script has
! 47: a check for this, but is not 100% foolproof.
! 48:
! 49: See below if you want to contribute.
! 50:
! 51:
! 52: Building
! 53: --------
! 54:
! 55: When building pimd from source you first need to run the `configure`
! 56: script to generate the file `config.mk`. The script relies on Bourne
! 57: shell standard features as well as expr and uname. Any optional pimd
! 58: features, such as `--enable-scoped-acls` are activated here as well.
! 59:
! 60: **Example:**
! 61:
! 62: ./configure --enable-scoped-acls && make
! 63:
! 64: sudo make install
! 65:
! 66: The configure script and Makefile supports de facto standard settings
! 67: and environment variables such as `--prefix=PATH` and `DESTDIR=` for the
! 68: install process. E.g., to install pimd to `/usr` instead of the default
! 69: `/usr/local`, but redirect to a binary package directory in `/tmp`:
! 70:
! 71: ./configure --prefix=/usr && make clean all
! 72: make VERSION=2.3.0-1 DESTDIR=/tmp/pimd-2.3.0-1 install
! 73:
! 74:
! 75: Configuration
! 76: -------------
! 77:
! 78: The configuration is kept in the file `/etc/pimd.conf`, the order of
! 79: the statements are in some cases important.
! 80:
! 81: PIM-SM is a designed to be a *protocol independent* multicast routing
! 82: protocol. As such it relies on unicast protocols like, e.g, OSPF, RIP,
! 83: or static routing entries, to figure out the path to all multicast
! 84: capable neighboring routers. This information is necessary in setups
! 85: with more than one route between a multicast sender and a receiver to
! 86: figure out which PIM router should be the active forwarder.
! 87:
! 88: However, pimd currently cannot retrieve the unicast routing distance
! 89: (preference) and metric of routes from the system, not from the kernel
! 90: nor a route manager like zebra. Hence, pimd currently needs to be setup
! 91: statically on each router using the desired distance and metric for each
! 92: active interface. If either the distance and/or the metric is missing
! 93: in an interface configuration, the following two defaults will be used:
! 94:
! 95: default-route-distance <1-255> default: 101
! 96: default-route-metric <1-1024> default: 1024
! 97:
! 98: By default pimd starts up on all interfaces it can find, using the above
! 99: defaults. To configure individual interfaces use:
! 100:
! 101: phyint <address | ifname> ...
! 102:
! 103: You can reference the interface via either its local IPv4 address or
! 104: its name, e.g., eth0. Some common interface settings are:
! 105:
! 106: * `disable`: Disable pimd on this interface, i.e., do not send or
! 107: listen for PIM-SM traffic
! 108:
! 109: * `dr-priority <1-4294967294>`: The DR Priority option, sent in all
! 110: all PIM Hello messages. Used instead of the IP address in all DR
! 111: elections, if all PIM routers in LAN advertise it. The higher, the
! 112: better, default 1.
! 113:
! 114: * `distance <1-255>`: The interface's admin distance value (also
! 115: confusingly referred to as *metric preference* in the RFC) in PIM
! 116: Assert messages. Used with `metric` to elect the active multicast
! 117: forwarding router. Defaults to `default-route-distance`
! 118:
! 119: * `metric <1-1024>`: The cost for traversing this router. Used with
! 120: the `preference` value above. Defaults to `default-route-metric`
! 121:
! 122: More interface settings are available, see the pimd(8) manual page for
! 123: the full details.
! 124:
! 125: The most notable feature of PIM-SM is that multicast is distributed from
! 126: so called Rendezvous Points (RP). Each RP handles distribution of one
! 127: or more multicast groups, pimd can be configured to advertise itself as
! 128: a candidate RP `rp-candidate`, and request to be static RP `rp-address`
! 129: for one or more multicast groups.
! 130:
! 131: rp-address <address> [<group>[/<LENGTH> | masklen <LENGTH]
! 132:
! 133: The `rp-address` setting is the same as the Cisco `ip pim rp-address`
! 134: setting to configure static Rendezvous Points. The first argument can
! 135: be an IPv4 address or a multicast group address. The default group and
! 136: prefix length is 224.0.0.0/16. Static RP's always have priority 1.
! 137:
! 138: rp-candidate [address | ifname] [time <10-16383>] [priority <0-255>]
! 139:
! 140: The Rendezvous Point candidate, or CRP, setting is the same as the Cisco
! 141: `ip pim rp-candidate` setting. Use it to control which interface that
! 142: should be used in RP elections.
! 143:
! 144: * `address | ifname`: Optional local IPv4 address, or interface name
! 145: to acquire address from. The default is to use the highest active
! 146: IP address.
! 147:
! 148: * `time <10-16383>`: The interval, in seconds, between advertising
! 149: this CRP. Default: 60 seconds
! 150:
! 151: * `priority <0-255>`: How important this CRP is compared to others.
! 152: The lower the value here, the more important the CRP. Like Cisco,
! 153: pimd defaults to priority 0 when this is left out
! 154:
! 155: In the CRP messages sent out by pimd, one or more multicast groups can
! 156: be advertised using the following syntax.
! 157:
! 158: group-prefix <group>[</LENGTH> | masklen <LENGTH>]
! 159:
! 160: Each `group-prefix` setting defines one multicast group and an optional
! 161: mask length, which defaults to 16 if left out. A maximum of 255
! 162: multicast group prefix records is possible for the CRP.
! 163:
! 164: To keep track of all Rendezvous Points in a PIM-SM domain there exists a
! 165: feature called *Bootstrap Router*. The elected BSR in a PIM-SM domain
! 166: periodically announces the RP set in Bootstrap messages. For details on
! 167: PIM BSR operation, see [RFC 5059](http://tools.ietf.org/search/rfc5059).
! 168:
! 169: bsr-candidate [address | ifname] [priority <0-255>]
! 170:
! 171: The configuration of a Candidate BootStrap Router (CBSR) is very similar
! 172: to that of CRP, except for the interval time. If either the address or
! 173: the interface name is left out pimd uses the highest active IP address.
! 174: If the priority is left out, `pimd` (like Cisco) defaults to priority 0.
! 175:
! 176: To *disable CRP and CBSR* completely in `pimd`, simply comment the two
! 177: lines out from your `pimd.conf`, and make sure `pimd` can find the file.
! 178: Because if `pimd` cannot find the file it will default to them enabled,
! 179: with defaults listed in the `pimd.conf` included in the distribution.
! 180:
! 181: In a PIM-SM domain there can be two, or more, paths from a designated
! 182: router (DR) for a multicast sender to reach a receiver. When receivers
! 183: begin joining multicast groups all data is received via the *shared
! 184: tree* (RPT) from each Rendezvous Point (RP). This is often not an
! 185: optimal route, so when the volume starts exceeding a configurable
! 186: threshold, on either the last-hop router or the RP itself, the router
! 187: will attempt to switch to the *shortest path tree* (SPT) from the
! 188: multicast source to the receiver.
! 189:
! 190: In versions of pimd prior to 2.2.0 this threshold was confusingly split
! 191: in two different settings, one for the DR and one for the RP. These
! 192: settings are still supported, for compatibility reasons and documented
! 193: in the man-page, but it is strongly recommended to change to the new
! 194: syntax instead:
! 195:
! 196: spt-threshold [rate <KBPS> | packets <NUM> | infinity] [interval <5-60>]
! 197:
! 198: Only slightly different from the Cisco `ip pim spt-threshold` setting,
! 199: pimd can trigger a switch to SPT on a rate or number of packets and you
! 200: can also tweak the poll interval. It's recommended to keep the interval
! 201: in the tens of seconds, the default is 100 sec. The default threshold
! 202: is set to zero packets, which will cause a switch over to the SPT after
! 203: the first multicast packet is received.
! 204:
! 205:
! 206: Example
! 207: -------
! 208:
! 209: # Interface eth0 is disabled, i.e., pimd will not run there.
! 210: phyint eth0 disable
! 211:
! 212: # On this LAN we have a lower numeric IP than other PIM routers
! 213: # but we want to take care of forwarding all PIM messages.
! 214: phyint eth1 dr-priority 10
! 215:
! 216: # Partake in BSR elections on eth1
! 217: bsr-candidate eth1
! 218:
! 219: # Offer to be an RP for all of 224.0.0.0/4
! 220: rp-candidate eth1
! 221: group-prefix 224.0.0.0 masklen 4
! 222:
! 223: # This is the built-in defaults, switch to SPT on first packet
! 224: spt-threshold packets 0 interval 100
! 225:
! 226:
! 227: Starting
! 228: --------
! 229:
! 230: Having set up the configuration file, you are ready to run pimd. As
! 231: usual, it is recommended that you start it manually first, to make sure
! 232: everything works as expected, before adding it to your system's startup
! 233: scripts, with any startup flags it might need.
! 234:
! 235: pimd [-c file] [-d subsys1[,...,subsysN]] [-s level]
! 236:
! 237: * `-c file`: Utilize the specified configuration file rather than the
! 238: default, `/etc/pimd.conf`
! 239: * `-d [subsys1,...,subsysN]`: Subsystems to enable debug for when
! 240: running the daemon. Optional argument, if left out, all subsystems
! 241: are enabled. Type `pimd -h` for a full list of subsystems
! 242: * `-s level`: Log level, one of `none`, `error`, `warning`, `notice`,
! 243: `info`, or `debug`. Default is `notice`
! 244:
! 245: **Example:**
! 246:
! 247: pimd -c /cfg/pimd.conf -digmp_proto,pim_jp,kernel,pim_register
! 248:
! 249: Notice the lack of spaces in the option argument to `-d`, the
! 250: long-option `--debug=igmp_proto,pim_jp,kernel,pim_register`is slightly
! 251: more readable.
! 252:
! 253:
! 254: Monitoring
! 255: ----------
! 256:
! 257: To see the virtual interface table, including neighboring PIM routers,
! 258: and the multicast routing table:
! 259:
! 260: pimd -r
! 261:
! 262: or to watch it continually:
! 263:
! 264: watch pimd -r
! 265:
! 266: In addition, pimd logs important events to the system logfile, in
! 267: particular at startup when parsing the `pimd.conf` configuration file.
! 268:
! 269:
! 270: Contributing
! 271: ------------
! 272:
! 273: pimd is maintained by [Joachim Nilsson][] at [GitHub][]. If you find
! 274: bugs, have feature requests, or want to contribute fixes or features,
! 275: check out the code from GitHub, including the submodules:
! 276:
! 277: git clone https://github.com/troglobit/uftpd
! 278: cd uftpd
! 279: make submodules
! 280:
! 281: When you pull from upstream, remember to also update the submodules
! 282: using `git submodule update`, see the file [CONTRIBUTING.md][contrib]
! 283: for further details.
! 284:
! 285:
! 286: [BSD license]: https://en.wikipedia.org/wiki/BSD_licenses
! 287: [github]: http://github.com/troglobit/pimd
! 288: [homepage]: http://troglobit.com/pimd.html
! 289: [changes]: https://github.com/troglobit/pimd/blob/master/ChangeLog.org
! 290: [the FTP]: http://ftp.troglobit.com/pimd/
! 291: [releases page]: https://github.com/troglobit/pimd/releases
! 292: [contrib]: https://github.com/troglobit/pimd/blob/master/CONTRIBUTING.md
! 293: [Joachim Nilsson]: http://troglobit.com
! 294: [Travis]: https://travis-ci.org/troglobit/pimd
! 295: [Travis Status]: https://travis-ci.org/troglobit/pimd.png?branch=master
! 296: [Coverity Scan]: https://scan.coverity.com/projects/3319
! 297: [Coverity Status]: https://scan.coverity.com/projects/3319/badge.svg
! 298:
! 299: <!--
! 300: -- Local Variables:
! 301: -- mode: markdown
! 302: -- End:
! 303: -->
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pimd