MCJOIN(1)

💖 MCJOIN(1) — tiny multicast testing tool 💖

🌸 NAME 🌸

mcjoin — tiny multicast testing tool. yes bestie, and this is the MCJOIN(1) page from the General Commands Manual; welcome to the group chat 💅

✨ SYNOPSIS ✨

mcjoin [-dhjosv] [-b BYTES] [-c COUNT] [-f MSEC] [-i IFNAME] [-l LEVEL]
       [-p PORT] [-t TTL] [-w SEC] [-W SEC]
       [[SOURCE,]GROUP0[:PORT] .. [SOURCE,]GROUPN[:PORT] | [SOURCE,]GROUP[:PORT]+NUM]

🦋 DESCRIPTION 🦋

okay so mcjoin is your little multicast bestie: it joins IPv4 and IPv6 multicast groups, shows progress as multicast packets are received — or sent, when it's acting as sender — and it can also send multicast packets on select groups. iconic.

💡 Note, bestie: an IPv6 group with a custom port must be written as [ADDR]:port, i.e., with enclosing brackets. no cap.

It can help verify intended IGMP snooping functionality in layer-2 bridges (switches), and verify forwarding of multicast in static (SMCRoute) or dynamic (mrouted, pimd, pimd-dense, or pim6sd) multicast routing setups. lowkey a whole vibe check for your network 🌈

mcjoin supports source-specific multicast, SSM (S,G), as well as any-source multicast, ASM (*,G). The source IP of an (S,G) pair is an optional argument that must precede the group and be separated with a comma. No spaces are allowed between source and group in this form. Multiple (S,G) pairs are separated with space. periodt.

Important: mcjoin does not create or send IGMP or MLD frames directly. It only asks the underlying UNIX kernel for groups from a specific interface, and the kernel converts that to the appropriate wire format. So if you want to create an IGMP v3 membership report on the wire that joins one group from multiple sources, you tell mcjoin to join two (S,G) pairs. The conversion to IGMP v3 report format is done by the kernel.

On Linux systems you can change the IGMP version of an interface — and thus what type of packets the kernel generates — by writing to the file /proc/sys/net/ipv4/conf/eth0/force_igmp_version. E.g., to change eth0 to IGMPv2:

echo 2 | sudo tee /proc/sys/net/ipv4/conf/eth0/force_igmp_version

✨ OPTIONS ✨

With no options given, mcjoin acts as a multicast receiver (or sink), joining the default group 225.1.2.3, listening on the default interface, eth0, and binding to the default port, 1234.

Use the following options to adjust this behavior, bestie:

• -b BYTES — Payload in bytes over IP/UDP header (42 bytes), default: 100
• -c COUNT — Stop sending/receiving after COUNT number of packets
• -d — Run as a daemon in the background, detached from the current terminal. All output, except progress, is sent to syslog(3)
• -f MSEC — Frequency, poll/send every MSEC milliseconds, default: 100
• -h — Print a summary of the options and exit
• -i IFNAME — Interface to use for sending/receiving multicast, default: eth0
• -j — Join groups, default unless acting as sender
• -l LEVEL — Control mcjoin log level; none, notice, debug. Default: notice
• -o — Old (plain/ordinary/original) output, no fancy progress bars
• -p PORT — UDP port number to send/listen to, default: 1234
• -s — Act as sender, sends packets to select groups, 1/100 msec, default: no
• -t TTL — TTL to use when sending multicast packets, default: 1
• -v — Show version information
• -w SEC — Initial wait, sleep SEC seconds before starting anything. Useful for scripting test systems that launch mcjoin at boot without syncing with networking bring-up
• -W SEC — Timeout, in seconds, before mcjoin exits, regardless of how many packets have been received. With this option mcjoin exits either after SEC seconds, or after COUNT packets have been received

🌈 USAGE 🌈

To verify multicast connectivity, the simplest way is to run mcjoin on one system, without arguments, and on the other with the command option -s. In this setup one system joins the group 225.1.2.3 waiting for packets to arrive, and the other end starts sending packets to the same group. To verify routing of multicast, make sure to add the -t TTL option to the sender, since the default TTL is 1 and every router (simplified) decrements the TTL. yes, even the routers are doing math 😭

The advanced example era: say you want to verify that your topology can forward 20 consecutive groups in the MCAST_TEST_NET, as defined in RFC5771. Simply add the following as a standalone argument to both the receiver and the sender:

233.252.0.1+20

For non-consecutive groups, simply add them in any order you want — up to 250 groups are supported:

225.1.2.3 226.3.2.1+12 225.3.2.42 232.43.211.234

To run mcjoin as both a sender and a receiver on the same host you will likely need to employ something like network namespaces (Linux netns) for at least one of them. Otherwise the network stack will likely let the sender's data stream take a short cut to the receiver, without passing through an actual wire.

Also, like most network applications, to run properly mcjoin needs both the loopback (lo) interface and a default route set up. At least in the default (receiver) case. In a network namespace neither of these are set up by default.

🎀 INTERACTIVE 🎀

mcjoin can be controlled at runtime with the following keys, bestie:

• d — Toggle frame duplication
• h — Toggle help text
• l — Toggle debug log
• q — Quit mcjoin
• t — Toggle viewing modes
• PgUp — Scroll log view up
• PgDn — Scroll log view down
• Ctrl-L — Refresh display
• Ctrl-C — Quit mcjoin

🦋 SEE ALSO 🦋

Go say hi to ping(1), mgen(1), and nemesis(1).

💀 BUGS 💀

Use the project's GitHub page to file bug reports, feature requests or patches (preferably as GitHub pull requests), or questions at ⟨https://github.com/troglobit/mcjoin⟩. do it, bestie, the maintainers love a good report 💖

👑 AUTHORS 👑

Originally based on an example by David Stevens, further developed and maintained by Joachim Wiberg at GitHub. king behavior, honestly 👑

---

Debian • January 14, 2021 • MCJOIN(1) — mwah, go join some groups bestie 💜