{"id":13577730,"url":"https://github.com/troglobit/pimd","last_synced_at":"2025-04-07T06:11:48.178Z","repository":{"id":782378,"uuid":"474865","full_name":"troglobit/pimd","owner":"troglobit","description":"PIM-SM/SSM multicast routing for UNIX and Linux","archived":false,"fork":false,"pushed_at":"2022-08-11T06:59:04.000Z","size":3354,"stargazers_count":206,"open_issues_count":33,"forks_count":90,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-03-31T05:04:51.162Z","etag":null,"topics":["bsd","bsd-license","c","linux","multicast","pim-router","pim-sm","pim-ssm","pimd","router","unix"],"latest_commit_sha":null,"homepage":"http://troglobit.com/projects/pimd/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/troglobit.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["troglobit"]}},"created_at":"2010-01-16T12:37:56.000Z","updated_at":"2025-03-08T08:48:12.000Z","dependencies_parsed_at":"2022-07-05T14:31:27.424Z","dependency_job_id":null,"html_url":"https://github.com/troglobit/pimd","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troglobit%2Fpimd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troglobit%2Fpimd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troglobit%2Fpimd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troglobit%2Fpimd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/troglobit","download_url":"https://codeload.github.com/troglobit/pimd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601448,"owners_count":20964864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bsd","bsd-license","c","linux","multicast","pim-router","pim-sm","pim-ssm","pimd","router","unix"],"created_at":"2024-08-01T15:01:23.888Z","updated_at":"2025-04-07T06:11:48.159Z","avatar_url":"https://github.com/troglobit.png","language":"C","funding_links":["https://github.com/sponsors/troglobit"],"categories":["C"],"sub_categories":[],"readme":"PIM-SM/SSM Multicast Routing for UNIX\n=====================================\n[![License Badge][]][License] [![GitHub Status][]][GitHub] [![Coverity Status][]][Coverity Scan]\n\nTable of Contents\n-----------------\n\n* [Introduction](#introduction)\n* [Configuration](#configuration)\n* [Running pimd](#running-pimd)\n* [Troubleshooting Checklist](#troubleshooting-checklist)\n* [Monitoring](#monitoring)\n* [Large Setups](#large-setups)\n* [Build \u0026 Install](#build--install)\n* [Building from GIT](#building-from-git)\n* [Contributing](#contributing)\n* [Origin \u0026 References](#origin--references)\n\n\nIntroduction\n------------\n\npimd is a lightweight, stand-alone PIM-SM/SSM multicast routing daemon\navailable under the free [3-clause BSD license][License].  This is the\nrestored original version from University of Southern California, by\nAhmed Helmy, Rusty Eddy and Pavlin Ivanov Radoslavov.\n\nToday pimd is maintained at [GitHub][].  This is the preferred way to\ndownload releases, access the GIT sources, report bugs, and send patches\nor pull requests.  Official release tarballs at the [homepage][] and at\nthe GitHub project's release directory.\n\npimd is developed on Linux and should work as-is out of the box on all\nmajor distributions.  Other UNIX variants; NetBSD, FreeBSD, and Illumos,\nmay also work, but do not receive the same amount of testing.\n\npimd ships with a useful `pimctl` tool, compatible with all PIM daemons\nfrom the same family: pimd, pimd-dense, pim6sd. It can be a very helpful\nlittle tool when debugging and learning PIM setups.  The pimctl API is\ndocumented in the file `src/ipc.c`, in case you want to use `socat` to\ntalk to pimd over its UNIX domain socket:\n\n    echo \"help\" |socat - UNIX-CONNECT:/var/run/pimd.sock\n\nFor a summary of changes for each release, see the [ChangeLog][].\n\n\nConfiguration\n-------------\n\nThe configuration is kept in the file `/etc/pimd.conf`, the order of\nthe statements are in some cases important.\n\nPIM-SM is a designed to be a *protocol independent* multicast routing\nprotocol.  As such it relies on unicast protocols like, e.g, OSPF, RIP,\nor static routing entries to figure out the reverse path to multicast\nsources.  This information is necessary in setups with more than one\nroute between a multicast sender and a receiver to figure out which PIM\nrouter should be the active forwarder.\n\nHowever, pimd currently cannot retrieve the unicast routing distance\n(preference) and metric of routes from the system, not from the kernel\nnor a route manager like zebra.  Hence, pimd currently needs to be setup\nstatically on each router using the desired distance and metric for each\nactive interface.  If either the distance and/or the metric is missing\nin an interface configuration, the following two defaults will be used:\n\n    default-route-distance   \u003c1-255\u003e     default: 101\n    default-route-metric     \u003c1-1024\u003e    default: 1024\n\nBy default pimd starts up on all interfaces it can find, using the above\ndefaults.  To configure individual interfaces use:\n\n    phyint \u003caddress | ifname\u003e ...\n\nYou can reference the interface via either its local IPv4 address or\nits name, e.g., eth0.  Some common interface settings are:\n\n   * `disable`: Disable pimd on this interface, i.e., do not send or\n     listen for PIM-SM traffic\n\n   * `dr-priority \u003c1-4294967294\u003e`: The DR Priority option, sent in all\n     all PIM Hello messages.  Used instead of the IP address in all DR\n     elections, if all PIM routers in LAN advertise it.  The higher, the\n     better, default 1.\n\n   * `distance \u003c1-255\u003e`: The interface's admin distance value (also\n     confusingly referred to as *metric preference* in the RFC) in PIM\n     Assert messages.  Used with `metric` to elect the active multicast\n     forwarding router.  Defaults to `default-route-distance`\n\n   * `metric \u003c1-1024\u003e`: The cost for traversing this router.  Used with\n     the `preference` value above. Defaults to `default-route-metric`\n\nMore interface settings are available, see the pimd(8) manual page for\nthe full details.\n\nThe most notable feature of PIM-SM is that multicast is distributed from\nso called Rendezvous Points (RP).  Each RP handles distribution of one\nor more multicast groups, pimd can be configured to advertise itself as\na candidate RP `rp-candidate`, and request to be static RP `rp-address`\nfor one or more multicast groups.\n\n    rp-address \u003caddress\u003e [\u003cgroup\u003e[/\u003cLENGTH\u003e | masklen \u003cLENGTH]\n\nThe `rp-address` setting is the same as the Cisco `ip pim rp-address`\nsetting to configure static Rendezvous Points.  The first argument can\nbe an IPv4 address or a multicast group address.  The default group and\nprefix length is 224.0.0.0/16.  Static RP's always have priority 1.\n\n    rp-candidate [address | ifname] [interval \u003c10-16383\u003e] [priority \u003c0-255\u003e] \\\n                 [group-prefix \u003cgroup\u003e[\u003c/LENGTH\u003e | masklen \u003cLENGTH\u003e]]\n\nThe Rendezvous Point candidate, or CRP, setting is the same as the Cisco\n`ip pim rp-candidate` setting.  Use it to control which interface that\nshould be used in RP elections.\n\n   * `address | ifname`: Optional local IPv4 address, or interface name\n     to acquire address from.  The default is to use the highest active\n     IP address.\n\n   * `interval \u003c10-16383\u003e`: The CRP advertisement interval, in seconds.\n     Default: 60 seconds\n\n   * `priority \u003c0-255\u003e`: How important this CRP is compared to others.\n     The lower the value here, the more important the CRP.  Like Cisco,\n     pimd defaults to priority 0 when this is left out\n\nIn the CRP messages sent out by pimd, one or more multicast groups can\nbe advertised using the following syntax.\n\n    group-prefix \u003cgroup\u003e[\u003c/LENGTH\u003e | masklen \u003cLENGTH\u003e]\n\nEach `group-prefix` setting defines one multicast group and an optional\nmask length, which defaults to 16 if left out.  A maximum of 255\nmulticast group prefix records is possible for the CRP.\n\nTo keep track of all Rendezvous Points in a PIM-SM domain there exists a\nfeature called *Bootstrap Router*.  The elected BSR in a PIM-SM domain\nperiodically announces the RP set in Bootstrap messages.  For details on\nPIM BSR operation, see [RFC 5059](http://tools.ietf.org/search/rfc5059).\n\n    bsr-candidate [address | ifname] [priority \u003c0-255\u003e] [interval \u003c10-26214\u003e]\n\nThe configuration of a Candidate BootStrap Router (CBSR) is very similar\nto that of CRP.  If either the address or the interface name is left out\n`pimd` uses the highest active IP address.  If the priority is omitted,\n`pimd` (like Cisco) defaults to priority 0.  If the interval is omitted,\nit defaults to the RFC value of 60 seconds.\n\nIn a PIM-SM domain there can be two, or more, paths from a designated\nrouter (DR) for a multicast sender to reach a receiver.  When receivers\nbegin joining multicast groups all data is received via the *shared\ntree* (RPT) from each Rendezvous Point (RP).  This is often not an\noptimal route, so when the volume starts exceeding a configurable\nthreshold, on either the last-hop router or the RP itself, the router\nwill attempt to switch to the *shortest path tree* (SPT) from the\nmulticast source to the receiver.\n\nIn versions of pimd prior to 2.2.0 this threshold was confusingly split\nin two different settings, one for the DR and one for the RP.  These\nsettings are still supported, for compatibility reasons and documented\nin the man-page, but it is strongly recommended to change to the new\nsyntax instead:\n\n    spt-threshold [rate \u003cKBPS\u003e | packets \u003cNUM\u003e | infinity] [interval \u003c5-60\u003e]\n\nOnly slightly different from the Cisco `ip pim spt-threshold` setting,\npimd can trigger a switch to SPT on a rate or number of packets and you\ncan also tweak the poll interval.  It's recommended to keep the interval\nin the tens of seconds, the default is 100 sec.  The default threshold\nis set to zero packets, which will cause a switch over to the SPT after\nthe first multicast packet is received.\n\n\n### Example\n\n    # Interface eth0 is disabled, i.e., pimd will not run there.\n    phyint eth0 disable\n\n    # On this LAN we have a lower numeric IP than other PIM routers\n    # but we want to take care of forwarding all PIM messages.\n    phyint eth1 dr-priority 10\n\n    # Partake in BSR elections on eth1\n    bsr-candidate eth1\n\n    # Offer to be an RP for all of 224.0.0.0/4\n    rp-candidate eth1\n    group-prefix 224.0.0.0 masklen 4\n\n    # This is the built-in defaults, switch to SPT on first packet\n    spt-threshold packets 0 interval 100\n\n\nRunning pimd\n------------\n\nHaving set up the configuration file, you are ready to run `pimd`.  As\nusual, it is recommended that you start it manually first, to make sure\neverything works as expected, before adding it to your system's startup\nscripts, with any startup flags it might need.\n\n    pimd [-hnrsv] [-f file] [-d subsys1[,...,subsysN]] [-l level]\n\n* `-n`: Run in foreground, with logs to stdout (for systemd and finit)\n* `-s`: Use syslog, default unless `-n`\n* `-c file`: Utilize the specified configuration file rather than the\n   default, `/etc/pimd.conf`\n* `-d [subsys1,...,subsysN]`: Subsystems to enable debug for when\n  running the daemon.  Optional argument, if left out, all subsystems\n  are enabled.  Type `pimd -h` for a full list of subsystems\n* `-l level`: Log level, one of `none`, `error`, `warning`, `notice`,\n   `info`, or `debug`.  Default is `notice`\n\n**Example:**\n\n    pimd -f /cfg/pimd.conf\n\nWhen running multiple instances of pimd, make sure to use the `-I ident`\nargument, otherwise the PID and IPC socket files will be overwritten and\nthe syslog will also be hard to follow.  Note, `-I` changes the default\n`.conf` filename pimd looks for as well, a complete identity change.\n\n\n### Enabling Debug\n\nRemember to set the correct log level when enabling debug messages,\nusually you need `-l debug`, and `-s` to force messages to syslog\nwhen running in the foreground (`-n`).\n\n    pimd -d igmp_proto,pim_jp,kernel,pim_register -l debug -n -s\n\n\n## Troubleshooting Checklist\n\n1. Check the TTL of incoming multicast.  Remember, the TTL of the\n   multicast stream must be \u003e1 to be routed.  Or rather, `\u003e` than then\n   `ttl-threshold` of the inbound `phyint`\n\n2. If you see `Permission denied` in your logs, you are most likely\n   having firewall, or SELinux, problems\n\n3. For PIM-SM, make sure you have a Rendezvous-Point (RP) in your\n   network.  Check `rp-candidate` (CRP) and `bsr-candidate` (CBSR)\n   settings in your `pimd.conf`, or `rp-address` if you prefer the\n   static RP approach\n\n4. Check the Linux `rp_filter` setting.  Many Linux systems have the\n   \"strict\" setting enabled, \"loose\" can work but may cause problems in\n   some setups.  We recommend disabling it entirely\n\n5. PIM is protocol *independent* so you must have unicast routeing in\n   place already for `pimd` to work.  Use `ping` to verify connectivity\n   between multicast sender and receiver\n\n\nMonitoring\n----------\n\nTo see the virtual interface table, including neighboring PIM routers,\nand the multicast routing table:\n\n    pimctl show interfaces\n    pimctl show neighbor\n    pimctl show mrt\n    ...\n\nThe default command is `pimctl show pim`.  To watch it continually\n(notice the `-c` flag to watch(1) to tell it to interpret the ANSI\nescape sequences):\n\n    watch -cd pimctl\n\nSee the `pimctl help` usage text for more commands (available only when\na running PIM daemon is available), or the pimctl(8) man page.\n\nAlso worth mentioning, `pimd` logs important events to the system log,\nin particular at startup when it parses the `pimd.conf` configuration\nfile.\n\n\nLarge Setups\n------------\n\npimd is limited to the number of `MAXVIFS` interfaces listed in the\nkernel headers.  In Linux see `/usr/include/linux/mroute.h`. \n\nTo overcome this limitation, adjust the kernel `#define` to, e.g., 1280,\nand configure pimd `--with-max-vifs=1280`.  Please note, this has only\nbeen tested with Linux and will likely not work with other kernels!\n\nWith this many interfaces the kernel may run out of memory to let pimd\nto enable IGMP on all interfaces.  In Linux, use sysctl to tweak the\nfollowing settings:\n\n    sysctl -w net.core.optmem_max=327680\n    sysctl -w net.ipv4.igmp_max_memberships=5120\n\n\nBuild \u0026 Install\n---------------\n\nThe configure script and Makefile supports de facto standard settings\nand environment variables such as `--prefix=PATH` and `DESTDIR=` for the\ninstall process.  E.g., to install pimd to `/usr` instead of the default\n`/usr/local`, but redirect install to a package directory in `/tmp`:\n\n    ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var\n\tmake\n    make DESTDIR=/tmp/pimd-2.3.2-1 install-strip\n\n\nBuilding from GIT\n-----------------\n\nIf you want to contribute, or simply just try out the latest but\nunreleased features, then you need to know a few things about the\n[GNU build system][buildsystem]:\n\n- `configure.ac` and a per-directory `Makefile.am` are key files\n- `configure` and `Makefile.in` are generated from `autogen.sh`\n- `Makefile` is generated by `configure` script\n\nTo build from GIT you first need to clone the repository and run the\n`autogen.sh` script.  This requires `automake` and `autoconf` to be\ninstalled on your system.\n\n    git clone https://github.com/troglobit/pimd.git\n    cd pimd/\n    ./autogen.sh\n    ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var \u0026\u0026 make\n\nGIT sources are a moving target and are not recommended for production\nsystems, unless you know what you are doing!\n\n\nContributing\n------------\n\npimd is maintained by [Joachim Wiberg][] at [GitHub][].  If you find\nbugs, have feature requests, or want to contribute fixes or features,\ncheck out the code from GitHub:\n\n\tgit clone https://github.com/troglobit/pimd\n\tcd pimd\n\nSee the file [CONTRIBUTING.md][contrib] for further details.\n\n\nOrigin \u0026 References\n-------------------\n\nPart of this program has been derived from mrouted.  The mrouted program\nis covered by the 3-clause BSD license in the accompanying file named\n[LICENSE.mrouted](doc/LICENSE.mrouted).\n\nThe mrouted program is COPYRIGHT 2002 by The Board of Trustees of Leland\nStanford Junior University.\n\n\n[License]:         https://en.wikipedia.org/wiki/BSD_licenses\n[License Badge]:   https://img.shields.io/badge/License-BSD%203--Clause-blue.svg\n[github]:          https://github.com/troglobit/pimd\n[homepage]:        https://troglobit.com/pimd.html\n[ChangeLog]:       https://github.com/troglobit/pimd/blob/master/ChangeLog.org\n[releases page]:   https://github.com/troglobit/pimd/releases\n[buildsystem]:     https://autotools.io/\n[contrib]:         https://github.com/troglobit/pimd/blob/master/.github/CONTRIBUTING.md\n[Joachim Wiberg]:  https://troglobit.com\n[GitHub]:          https://github.com/troglobit/pimd/actions/workflows/build.yml/\n[GitHub Status]:   https://github.com/troglobit/pimd/actions/workflows/build.yml/badge.svg\n[Coverity Scan]:   https://scan.coverity.com/projects/3319\n[Coverity Status]: https://scan.coverity.com/projects/3319/badge.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftroglobit%2Fpimd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftroglobit%2Fpimd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftroglobit%2Fpimd/lists"}