{"id":16164261,"url":"https://github.com/troglobit/mcjoin","last_synced_at":"2025-04-10T03:52:34.900Z","repository":{"id":43323797,"uuid":"53221441","full_name":"troglobit/mcjoin","owner":"troglobit","description":"Simple multicast testing application","archived":false,"fork":false,"pushed_at":"2024-07-22T06:33:56.000Z","size":752,"stargazers_count":168,"open_issues_count":3,"forks_count":31,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-10T03:52:23.015Z","etag":null,"topics":["client-server","ipv4","ipv6","linux","multicast","multicast-applications","testing","unix"],"latest_commit_sha":null,"homepage":"https://github.com/troglobit/mcjoin/releases","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","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":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["troglobit"]}},"created_at":"2016-03-05T20:21:46.000Z","updated_at":"2025-03-29T14:03:10.000Z","dependencies_parsed_at":"2024-10-25T17:08:37.518Z","dependency_job_id":"66465bcc-1557-4c32-878a-423f4e49cf12","html_url":"https://github.com/troglobit/mcjoin","commit_stats":{"total_commits":377,"total_committers":10,"mean_commits":37.7,"dds":0.03448275862068961,"last_synced_commit":"b2162a7d547e45f1437b063252b719ba9bb04115"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troglobit%2Fmcjoin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troglobit%2Fmcjoin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troglobit%2Fmcjoin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troglobit%2Fmcjoin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/troglobit","download_url":"https://codeload.github.com/troglobit/mcjoin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154998,"owners_count":21056542,"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":["client-server","ipv4","ipv6","linux","multicast","multicast-applications","testing","unix"],"created_at":"2024-10-10T02:45:59.151Z","updated_at":"2025-04-10T03:52:34.878Z","avatar_url":"https://github.com/troglobit.png","language":"C","funding_links":["https://github.com/sponsors/troglobit"],"categories":[],"sub_categories":[],"readme":"m c j o i n - tiny multicast testing tool\n=========================================\n[![License Badge][]][License] [![GitHub Status][]][GitHub] [![Coverity Status][]][Coverity Scan]\n\n[mcjoin(1)](https://man.troglobit.com/man1/mcjoin.1.html) is a simple\nand easy-to-use tool to test IPv4 and IPv6 multicast, featuring:\n\n- a multicast generator (server)\n- a multicast data sink (client)\n- support for join/send to one or more groups\n- support for both any source and source specific multicast:\n  - ASM (*,G)\n  - SSM (S,G)\n- support for both IPv4 \u0026 IPv6\n- support for the following operating systems:\n  - Linux (GLIBC, musl libc)\n  - FreeBSD\n  - Apple macOS\n  - OpenSolaris/Illumos\n- no support for the following due to lack of [RFC3678][] support:\n  - NetBSD\n  - OpenBSD\n\n\u003e latest release available here: https://github.com/troglobit/mcjoin/releases\n\n\nexample\n-------\n\nthis is a fairly odd example, joining multiple ipv6 asm groups and a\nsingle ipv4 ssm group. the purpose is only to show that it's possible.\n\n    mcjoin ff2e::42 ff2e::43 ff2e::44 ff2e::45 225.1.2.3\n\n![mcjoin receiver](doc/mcjoin-recv.jpg)\n\nthe sender needs to have an ipv6 (and ipv4) address on the egressing\ninterface. here the system only has an ipv6 address.\n\n    mcjoin -s ff2e::42\n\n![mcjoin sender](doc/mcjoin-send.jpg)\n\nby default, mcjoin use the ipv4 group 225.1.2.3 (which is very easy to\nspot also when translated to mac multicast, [RFC1112][]). however, for\ntesting purposes you may want to instead use the `MCAST_TEST_NET` from\n[RFC5771][], `233.252.0.0/24`, or possibly test group `232.43.211.234`,\nUDP port `4321`, as defined in [this IETF draft][1].\n\nfor testing IPv6 you can use ff2e::42.  for ipv6 groups the ipv6 address\nof the outbound interface will be used.\n\n\u003e **remember:** to set ipv4 and/or ipv6 address on the outbound interface!\n\nusage\n-----\n\nwithout any arguments `mcjoin` defaults to act as a receiver, performing\nan IPv4 ASM join (*,G) of group `225.1.2.3`, UDP port `1234`.  to act as\na sender of the same group and port, add `-s` to the command line.\n\n    $ mcjoin -h\n    \n    Usage: mcjoin [-dhjosv] [-c COUNT] [-f MSEC] [-i IFACE] [-l LEVEL]\n                  [-p PORT] [-t TTL] [-w SEC]\n                  [[SOURCE,]GROUP0 .. [SOURCE,]GROUPN | [SOURCE,]GROUP+NUM]\n    \n    Options:\n      -b BYTES    Payload in bytes over IP/UDP header (42 bytes), default: 100\n      -c COUNT    Stop sending/receiving after COUNT number of packets\n      -d          Run as daemon in background, output except progress to syslog\n      -f MSEC     Frequency, poll/send every MSEC milliseconds, default: 100\n      -h          This help text\n      -i IFACE    Interface to use for sending/receiving multicast, default: eth0\n      -j          Join groups, default unless acting as sender\n      -l LEVEL    Set log level; none, notice*, debug\n      -o          Old (plain/ordinary) output, no fancy progress bars\n      -p PORT     UDP port number to listen to, default: 1234\n      -s          Act as sender, sends packets to select groups\n      -t TTL      TTL to use when sending multicast packets, default 1\n      -v          Display program version\n      -w SEC      Initial wait before opening sockets\n      -W SEC      Timeout, in seconds, before mcjoin exits\n\n    Bug report address : https://github.com/troglobit/mcjoin/issues\n    Project homepage   : https://github.com/troglobit/mcjoin/\n\nthe `SOURCE` argument is optional, but when used it must be of the same\naddress family as the group.  to join multiple groups, either list them\nall on the command line, separated with space, or use the `+NUM` syntax.\nat the moment max 2048 groups can be joined.\n\n\ntroubleshooting\n---------------\n\nthe multicast producer, `mcjoin -s`, can send without a default route,\nbut the sink (your receiver) need a net route back to the sender (or a\ndefault route), or reverse-path filtering (RPF) disabled to be able to\nreceive the UDP stream.  the sink will be able to start without an IP\naddress or route, as long as the interface is UP and allows MULTICAST,\nthe IGMP or MLD join frames will also be sent while you wait for an\naddress+route, but the kernel will (likely) not forward any frames to\nmcjoin even though it may be arriving at the interface if you check with\ntcpdump.\n\nin particular, this issue will arise if you run `mcjoin` in isolated\nnetwork namespaces in Linux.  e.g.\n\n    ip netns add sink\n    ip link set eth2 netns sink\n    ip netns exec sink /bin/bash\n    ip address add 127.0.0.1/8 dev lo\n    ip link set lo up\n    ip link set eth2 name eth0\n    ip address add 10.0.0.42/24 dev eth0\n    ip link set eth0 up\n    ip route add default via 10.0.0.1\n    mcjoin\n\ndepending on the route setup, and number of interfaces on a multihomed\nsystem, you may also need to verify that you don't have strict reverse\npath filtering (RPF) enabled.  on Linux `rp_filter` can be set to either\n0 (no filtering), 1 (strict), or 2 (loose filtering), the latter is the\nmost common for distributions today.  the difference between 1 and 2 is\nthat 1 (strict) checks for the *best* route, while 2 checks for any\nroute back to the sender.  see RFC3704 for more on reverse path\nfiltering.\n\n\ncaveat\n------\n\nusually there is a limit of 20 group joins per socket in UNIX, this is\nthe `IP_MAX_MEMBERSHIPTS` define.  on Linux this can be tweaked using a\n`/proc` setting:\n\n    echo 40 \u003e /proc/sys/net/ipv4/igmp_max_memberships\n\nmcjoin has a different approach, it opens a unique socket per each group\nto join and for each socket disables the odd `IP_MULTICAST_ALL` socket\noption, which is enabled by default.  Citing the Linux `ip(7)` man page,\nemphasis added:\n\n\u003e **IP_MULTICAST_ALL** *(since Linux 2.6.31)*\n\u003e\n\u003e This option can be used to modify the delivery policy of multicast\n\u003e messages to sockets bound to the wildcard INADDR_ANY address.  The\n\u003e argument is a boolean integer (defaults to 1).  If set to 1, the\n\u003e socket will **receive messages from all the groups that have been\n\u003e joined globally on the whole system**.  Otherwise, it will deliver\n\u003e messages only from the groups that have been explicitly joined (for\n\u003e example via the IP_ADD_MEMBERSHIP option) on this particular socket.\n\nthe same applies to `ipv6(7)`, although the `IPV6_MULTICAST_ALL` socket\noption has only existed since Linux 4.20.\n\nhence, by default all multicast applications in UNIX will receive all\nmulticast frames from all groups joined by all other applications on\nthe same system ...\n\n... which IMO is a weird default since multicast by default is opt-in,\nnot opt-out, which is what POSIX makes it.  OK, maybe it's not mandated\nby POSIX, and (unregulated) multicast is akin to broadcast, but still!\nI bet most developer's don't know about this.\n\n\ntesting on the same machine\n---------------------------\n\nin many cases while using mcjoin for testing networking equipment, you\nneed to use at least two local network interfaces (nics): one acting as\nmulticast sender and one as receiver.  (often you need multiple sender\ninterfaces, which can be physical, virtual or vlan interfaces.)\n\n            .-------.\n            |       |\n        .---+  dut  +---.\n        |   |       |   |\n        |   '-------'   |\n        |               |\n    .- eth0 ---------- eth1 -.\n    |                        |\n    |           pc           |\n    |                        |\n    '------------------------'\n\nto get this to work on linux you need to *disable* the `rp_filter` and\n*enable* `accept_local` sysctl settings for the involved interfaces.\nhere is an example of how to adjust this for *all* interfaces. use with\ncare, this can cause a lot of other problems if you use the same pc for\nother purposes as well:\n\n    $ cd /etc/sysctl.d/\n    $ cat 10-network-security.conf\n    # Allow receiving IP packets from local interfaces, useful for testing\n    # rigs where looping packets via networking infrastructure.\n    net.ipv4.conf.default.accept_all=1\n    net.ipv4.conf.all.accept_all=1\n    \n    # Disable Source Address Verification in all interfaces to, usually set\n    # to 1 to prevent some spoofing attacks.  But for a testing rig this is\n    # usually the source of many woes, in particular for multicast testing.\n    net.ipv4.conf.default.rp_filter=0\n    net.ipv4.conf.all.rp_filter=0\n\n\nbuild \u0026 install\n---------------\n\nthe [GNU Configure \u0026 Build][buildsystem] system use `/usr/local` as the\ndefault install prefix.  for most use-cases this is fine, but if you\nwant to change this to `/usr` use the `--prefix=/usr` configure option:\n\n    $ ./configure --prefix=/usr\n    $ make -j5\n    $ sudo make 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 Configure \u0026 Build][buildsystem] system:\n\n- `configure.ac` and a per-directory `Makefile.am` are key files\n- `configure` and `Makefile.in` are generated from `autogen.sh`,\n  they are not stored in GIT but automatically generated for the\n  release tarballs\n- `Makefile` is generated by `configure` script\n\nto build from GIT; clone the repository and run the `autogen.sh` script.\nthis requires `automake` and `autoconf` to be installed on your system.\n(if you build from a released tarball you don't need them.)\n\n    git clone https://github.com/troglobit/mcjoin.git\n    cd mcjoin/\n    ./autogen.sh\n    ./configure \u0026\u0026 make\n    sudo make install-strip\n\n\n[1]:               http://tools.ietf.org/html/draft-ietf-mboned-ssmping-08\n[RFC1112]:         https://tools.ietf.org/html/rfc1112\n[RFC3678]:         https://tools.ietf.org/html/rfc3678\n[RFC5771]:         https://tools.ietf.org/html/rfc5771\n[License]:         https://en.wikipedia.org/wiki/ISC_license\n[License Badge]:   https://img.shields.io/badge/License-ISC-blue.svg\n[GitHub]:          https://github.com/troglobit/mcjoin/actions/workflows/build.yml/\n[GitHub Status]:   https://github.com/troglobit/mcjoin/actions/workflows/build.yml/badge.svg\n[Coverity Scan]:   https://scan.coverity.com/projects/9108\n[Coverity Status]: https://scan.coverity.com/projects/9108/badge.svg\n[buildsystem]:     https://airs.com/ian/configure/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftroglobit%2Fmcjoin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftroglobit%2Fmcjoin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftroglobit%2Fmcjoin/lists"}