Annotation of embedaddon/pimd/README.md, revision 1.1.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