FAQ

Frequently Asked Questions

How do I get this running?

(assuming python3 is set up and installed)

# cd /MY-AWESOME-DEV-PATH
# Retrieve a copy of the project, for example clone the source repository
git clone https://github.com/reactive-firewall/multicast.git multicast && cd ./multicast

# Make sure you are using stable if in production
git checkout stable

# Optionally check your environment is compatible
# make clean ; make test ; make clean ;

# Install the module
make install ;

# Use the module
python3 -m multicast --help ;

DONE

If all went well, multicast is now installed and working :tada:

How do I use this multicast to receive some UDP multicast?

(assuming multicast is set up, installed and you want to listen on 0.0.0.0)

# cd /MY-AWESOME-DEV-PATH
python3 -m multicast --daemon --use-std HEAR --port 59595 --group 224.0.0.1

Most users will want to stick to using HEAR when receiving multicast from the CLI. Alternatively, users can use RECV (by omitting the --daemon flag) to receive individual UDP messages, no more than one at a time.

[!IMPORTANT] Caveat: RECV is much more useful if actually used in a loop like:

# cd /MY-AWESOME-DEV-PATH
while true ; do  # until user Ctrl+C interrupts
    python3 -m multicast --use-std RECV --port 59595 --group 224.0.0.1 --groups 224.0.0.1
done

How do I use this to send UDP Multicast?

(assuming multicast is set up and installed)

# cd /MY-AWESOME-DEV-PATH
python3 -m multicast SAY --group 224.0.0.1 --port 59595 --message "Hello World!"

What is the basic API via python (instead of bash like above)?

[!WARNING] Caveat: this module is still a BETA Here is how it is tested right now

import multicast
import random  # for random port

# set up some stuff
_fixture_PORT_arg = int(random.SystemRandom().randint(49152, 65535))
_fixture_mcast_GRP_arg = "224.0.0.1"  # only use dotted notation for multicast group addresses
_fixture_host_BIND_arg = "224.0.0.1"

# spawn a listening proc

def printLoopStub(func):
    for i in range( 0, 5 ):
        print( str( func() ) )

@printLoopStub
def inputHandler():
    test_RCEV = multicast.recv.McastRECV()
    out_string = str()
    (didWork, buffer_string) = test_RCEV.doStep(
        groups=[_fixture_mcast_GRP_arg], port=_fixture_PORT_arg,
        iface=None, group=_fixture_host_BIND_arg
    )
    if didWork:
        out_string += buffer_string
    return out_string

inputHandler()

# alternatively listen as a server
# import multicast  # if not already done.
from multiprocessing import Process as Process

_fixture_HEAR_kwargs = {
        "is_daemon": True,
        "port": _fixture_PORT_arg,
        "group": _fixture_host_BIND_arg
    }
p = Process(
    target=multicast.hear.McastHEAR().doStep,
    name="HEAR", kwargs=_fixture_HEAR_kwargs
)
p.daemon = _fixture_HEAR_kwargs["is_daemon"]
p.start()

# ... use CTL+C (or signal 2) to shutdown the server 'p'

and elsewhere (like another function or even module) for the sender:


# assuming already did 'import multicast as multicast'

_fixture_SAY_args = [
    "--port", _fixture_PORT_arg,
    "--group", _fixture_mcast_GRP_arg,
    "--message", "'test message'"
]
try:
    multicast.__main__.McastDispatch().doStep(["SAY", _fixture_SAY_args])
    # Hint: use a loop to repeat or different arguments to vary message.
except Exception:
    p.join()
    raise RuntimeError("multicast seems to have failed.")

# clean up some stuff
p.join() # if not already handled don't forget to join the process and other overhead
didWork = (int(p.exitcode) <= int(0)) # if you use a loop and need to know the exit code

[!WARNING] Caveat: the above examples assume the reader is knowledgeable about general IPC theory and the standard python multiprocessing module and its use.

Here is a more CLI focused way to test as another example of how to use the module.

What are the defaults?

Default Multicast Group

[!IMPORTANT] The default multicast group address is 224.0.0.1.

From the documentation:

The Value of “224.0.0.1” is chosen as a default multicast group as per RFC-5771 on the rational that this group address will be treated as a local-net multicast (caveat: one should use link-local for ipv6).

Default Multicast Bind Address

[!NOTE] The default multicast bind address is the default group. This is efectivly 224.0.0.1.

Default TTL

[!IMPORTANT] The default multicast Time-to-Live (TTL) is 1.

From RFC-1112 §6.1

… If the upper-layer protocol chooses not to specify a time-to-live, it should default to 1 for all multicast IP datagrams, so that an explicit choice is required to multicast beyond a single network.

From the documentation:

A Value of 1 (one TTL) is chosen as per RFC-1112 §6.1 on the rational that an explicit value that could traverse beyond the local connected network should be chosen by the caller rather than the default value. This is in line with the principle of none, one or many.

Default Port

[!IMPORTANT] The default UDP port used by multicast is 59595.

From the documentation:

Arbitrary port to use by default, though any dynamic and free port would work.

While developers and network administrators must consider other factors in real-world deployments, it is fair to say any free port in the dynamic or “ephemeral” port range of 49152-65535 should work as far as this Multicast module is concerned.

  • For SAY the port refers to the destination port.

  • for RECV and HEAR the port refers to the port to listen on.

[!CAUTION] It is best to specify the port in use at this time as the default has yet to be properly assigned ( see related reactive-firewall/multicast#62 )

CLI exit code meanings

0 success

1 non-success - and is often accompanied by warnings or errors

2-225 failure of specific reason

  • Any exit value outside the range of 0-255 inclusive should be decoded with the formula: | input % 256 | which will yield the correct exit code.

[!NOTE] These are inline with CEP-8’s POSIX-based guidelines.

How do I build the documentation?

  • Typically, the documentation will be automatically built by CI/CD and posted to the official documentation site.

  • However, if one still wishes to build the documentation manually, there is a make target specifically for this:

    make build-docs

Building Documentation with a Custom Git Reference

By default, the documentation links to the stable branch on GitHub. To override this and link to the specific commit you’re working on, set the DOCS_BUILD_REF environment variable:

# shellcheck disable=SC2155
export DOCS_BUILD_REF=$("${GIT:-git}" rev-parse --verify HEAD)
make build-docs  # or your own documentation build command

This command dynamically sets DOCS_BUILD_REF to the current Git commit hash, ensuring that documentation links point to the exact version of your code.