Simple Multicast Routing for UNIX

Table of Contents

• Introduction
• Running
• Configuration
• Build & Install
• Building from GIT
• Contributing
• Origin & References

Introduction

mrouted is the original implementation of the DVMRP multicast routing protocol, RFC 1075. It only works with IPv4 networks. For more advanced setups, the pimd project or pimd-dense project, for IPv6 the pim6sd project may be of interest.

mrouted is simple to use. DVMRP is derived from RIP, which means it works stand-alone without any extra network setup required. You can get up and running in a matter of minutes. Use the built-in IP-in-IP tunneling support, or GRE, to traverse Internet or intranets.

mrouted is developed on Linux and works as-is out of the box. Other UNIX variants should also work, but are not as thoroughly tested.

Manual pages available online:

• mrouted(8)
• mroutectl(8)
• mrouted.conf(5)

Running

mrouted does not require a .conf file. When it starts up it probes all available interfaces and starts peering with any DVMRP capable neighbor. Multicast is forwarded to end-devices that join a group using IGMPv1, IGMPv2, or IGMPv3. For LANs where there may be hosts that do not speak IGMP, or where certain groups should always be forwarded, a static-group setting is available in mrouted.conf.

Use mgen(1), mcjoin(1), or iperf to send IGMP join packets and multicast data on the LAN to test your multicast routing setup. Use the mroutectl tool to query a running mrouted for status.

NOTE: Beware of the TTL value in the IP header of your multicast data. It defaults to 1 on most operating systems, which means nothing will be routed by default!

For the native mrouted tunnel to work in Linux based systems, you need to have the "ipip" kernel module loaded or as built-in:

modprobe ipip

Alternatively, you may of course also set up GRE tunnels between your multicast capable routers.

If you have many interfaces on your system you may want to look into the no phyint setting in [mroute.conf(5)][]. Linux users may also need to adjust /proc/sys/net/ipv4/igmp_max_memberships to a value larger than the default 20. mrouted needs 3x the number of interfaces (vifs) for the relevant control protocol groups. The kernel (Linux & BSD) maximum number of interfaces to use for multicast routing is 32.

Note: mrouted must run with sufficient capabilities, or as root.

Configuration

mrouted reads its configuration file from /etc/mrouted.conf, if it exists. You can override the default by specifying an alternate file when invoking mrouted:

mrouted -f /path/file.conf

mrouted can be reconfigured at runtime like any regular UNIX daemon with SIGHUP, or mroutectl restart, to activate changes made to its configuration file. The PID is saved in the file /run/mrouted.pid for your scripting needs.

By default, mrouted configures itself to act as a multicast router on all multicast capable interfaces. Hence, you do not need to explicitly configure it, unless you need to setup tunnel links, change the default operating parameters, disable multicast routing over a specific physical interfaces, or have dynamic interfaces.

Note: you need to have IP Multicast Routing enabled in the kernel as well. How this is achieved is outside the scope of this README.

For more help, see the mrouted(8) and mrouted.conf(5) man pages.

Build & Install

Debian/Ubuntu

curl -sS https://deb.troglobit.com/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://deb.troglobit.com/debian stable main" | sudo tee /etc/apt/sources.list.d/troglobit.list
sudo apt-get update && sudo apt-get install mrouted

Building from Source

Download the latest official versioned mrouted release. Official releases contain all the necessary files, unlike building from GIT. mrouted has no external dependencies except for a standard C library.

• https://github.com/troglobit/mrouted/releases

The configure script and Makefile supports de facto standard settings and environment variables such as --prefix=PATH and DESTDIR= for the install process. For example, to install mrouted to /usr, instead of the default /usr/local, and redirect install to a package directory in /tmp:

./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
make
make DESTDIR=/tmp/mrouted-4.0-1 install-strip

Note: On some systems --runstatedir may not be available in the configure script, try --localstatedir=/var instead.

Building from GIT

If you want to contribute, or simply just try out the latest but unreleased features, then you need to know a few things about the GNU build system:

• configure.ac and a per-directory Makefile.am are key files
• configure and Makefile.in are generated from autogen.sh
• Makefile is generated by configure script

To build from GIT you first need to clone the repository and run the autogen.sh script. This requires automake and autoconf to be installed on your system.

git clone https://github.com/troglobit/mrouted.git
cd mrouted/
./autogen.sh
./configure && make

GIT sources are a moving target and are not recommended for production systems, unless you know what you are doing!

Contributing

The basic functionality has been tested thoroughly over the years, but that does not mean mrouted is bug free. Please report bugs, feature requests, patches and pull requests at GitHub.

Origin & References

The mrouted routing daemon was developed by David Waitzman, Craig Partridge, Steve Deering, Ajit Thyagarajan, Bill Fenner, David Thaler and Daniel Zappala. With contributions by many others.

The last release by Mr. Fenner was 3.9-beta3 on April 26 1999 and mrouted has been in "beta" status since then. Several prominent UNIX operating systems, such as AIX, Solaris, HP-UX, BSD/OS, NetBSD, FreeBSD, OpenBSD as well as most GNU/Linux based distributions have used that beta as a de facto stable release, with (mostly) minor patches for system adaptations. Over time however many dropped support, but Debian and OpenBSD kept it under their wings.

In March 2003 OpenBSD, led by the fearless Theo de Raadt, managed to convince Stanford to release mrouted under a fully free license, the 3-clause BSD license. Unfortunately, and despite the license issue being corrected by OpenBSD, in February 2005 Debian dropped mrouted as an "obsolete protocol".

For a long time the OpenBSD team remained the sole guardian of this project. In 2010 Joachim Wiberg revived mrouted on GitHub based on the last release by Bill Fenner, the mrouted-3.9beta3+IOS12.tar.gz tarball. This project has integrated all (?) known patches and continuously track the OpenBSD project, which is based on the 3.8 release, for any relevant fixes.

Copyright © 2002 The Board of Trustees of the Leland Stanford Junior University

Permission is hereby granted to STANFORD's rights, free of charge, to any
person obtaining a copy of this Software and associated documentation files
("MROUTED"), to deal in MROUTED without restriction, including without
limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of MROUTED, and to permit persons to whom
MROUTED is furnished to do so, subject to the following conditions:

1) The above copyright notice and this permission notice shall be included
   in all copies or substantial portions of the MROUTED.

2) Neither the STANFORD name nor the names of its contributors may be used
   in any promotional advertising or other promotional materials to be
   disseminated to the public or any portion thereof nor to use the name of
   any STANFORD faculty member, employee, or student, or any trademark,
   service mark, trade name, or symbol of STANFORD or Stanford Hospitals
   and Clinics, nor any that is associated with any of them, without
   STANFORD's prior written consent.  Any use of STANFORD's name shall be
   limited to statements of fact and shall not imply endorsement of any
   products or services.

3) MROUTED IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
   ARISING FROM, OUT OF OR IN CONNECTION WITH MROUTED OR THE USE OR OTHER
   DEALINGS IN THE MROUTED.

Contributing to mrouted

mrouted is a very old project. As such it has a lot of history that sometimes creep up through the cracks. Bugs!

Bugs can be missing or unclear documentation, faulty legacy behavior, missing key features or support for a new cool operating system. Or simple things, like speling errors or too frequent, or missing logs.

mrouted exists on GitHub for this exact purpose -- to fix bugs, collaboratively.

We welcome any and all help in the form of bug reports, fixes, patches for new features -- preferably as GitHub pull requests, submitting a pull request practically guarantees inclusion ... other methods are of course also possible: emailing the maintainer a patch or even a raw file, or simply emailing a feature request or an alert for a problem. For email questions/requests/alerts there is always the risk of memory exhaustion on the part of the maintainer.

Coding Style

Tip: Adapt your code to what the surrounding code looks like!

mrouted is written in C. C is an old language and sometimes that age is clearly visible. The current maintainer has tried to (re)enforce a consistent and more modern C style, without having to completly re-indent the whole code base.

First of all, lines are allowed to be longer than 72 characters these days. In fact, there exist no enforced maximum, but keeping it around 100 chars is good practice.

mrouted use leading four spaces in functions and structs. The next level use eight spaces, but the original authors used tab for that level. A switch() has its case statements indented four spaces ... but then it is more or less KNF.

In Emacs this coding style can be achieved by using the following footer applied to a C file:

/**
 * Local Variables:
 *  indent-tabs-mode: t
 *  c-file-style: "cc-mode"
 * End:
 */

The current maintainer has considered shifting the original coding style to FULL KNF several times, but decided against changing to keep with the intent of the original authors.

Commit Messages

Commit messages exist to track why a change was made. Try to be as clear and concise as possible in your commit messages, and always, be proud of your work and set up a proper GIT identity for your commits:

git config --global user.name "Jane Doe"
git config --global user.email jane.doe@example.com

Example commit message from the Pro Git online book, notice how git commit -s is used to automatically add a Signed-off-by:

Brief, but clear and concise summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as
the subject of an email and the rest of the text as the body.  The
blank line separating the ummary from the body is critical (unless
you omit the body entirely); tools like rebase can get confused if
you run the two together.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

Signed-off-by: Jane Doe <jane.doe@example.com>

Target Systems

mrouted mainly targets modern UNIX systems and has been tested on both Debian and Ubuntu for Linux, FreeBSD, and NetBSD. Please consider these targets when submitting changes. If you cannot test on them do this, be prepared that your feature/fix will likely be delayed by the maintainer, who will attempt to test and in some cases port the feature for you.

Code of Conduct

It is expected of everyone engaging in the project to, in the words of Bill & Ted; be excellent to each other.

Contributor Code of Conduct

As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery
• Personal attacks
• Trolling or insulting/derogatory comments
• Public or private harassment
• Publishing other's private information, such as physical or electronic addresses, without explicit permission
• Other unethical or unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.

This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

This Code of Conduct is adapted from the Contributor Covenant, version 1.2.0.

Reporting a Vulnerability

Please report security issues privately, using the Report a vulnerability button under Security on GitHub. That opens a draft advisory only you and the maintainer can see, and it is where a CVE is requested if one is warranted.

If you cannot use GitHub, email the maintainer directly, see the AUTHORS section of the mrouted(8) manual page. Please do not open a public issue for something you believe is exploitable until a fix is available.

Include the version, or git commit, you tested, the configuration needed to reach the problem, and how to trigger it. A packet capture or a small reproducer is very welcome. You will be credited in the advisory and in the ChangeLog, unless you would rather not be.

Supported Versions

Only the latest release is supported. Fixes go on the master branch and into the next release; there are no separate maintenance branches, and no backports to older releases. Distributors are welcome to cherry-pick.

mrouted implements DVMRP, a protocol from 1988 which has no authentication of any kind. Any host able to send IGMP to the router is able to speak DVMRP to it, so packet parsing bugs are usually remotely triggerable by design. Use the phyint and tunnel settings to limit where mrouted listens, and filter protocol 2 at your borders.