SnowSignal 0.1.1__py3-none-any.whl

snowsignal/__main__.py

@@ -0,0 +1,12 @@
+import asyncio
+import sys
+from asyncio.log import logger
+
+from .snowsignal import main
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logger.debug("Stopped by KeyboardInterrupt")
+        sys.exit(1)

snowsignal/configure.py

@@ -0,0 +1,106 @@
+"""Configuration for SnowSignal
+uses configargparse https://pypi.org/project/ConfigArgParse/
+"""
+
+import logging
+from collections.abc import Sequence
+from typing import NamedTuple
+
+import configargparse
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigArgs(NamedTuple):
+    """This bit of weirdness allows us to use strong type hinting with Argparse
+    or equivalent tools. See https://dev.to/xowap/the-ultimate-python-main-18kn"""
+
+    target_interface: str
+    broadcast_port: int
+    mesh_port: int
+    other_relays: list[str]
+    log_level: str
+
+
+def configure(argv: Sequence[str] | None = None) -> ConfigArgs:
+    """Setup configuration for the SnowSignal service"""
+
+    p = configargparse.ArgParser()
+    # Remember to add new arguments to the Args class above!
+    p.add_argument(
+        "-t",
+        "--target-interface",
+        env_var="TARGET_INTERFACE",
+        default="eth0",
+        type=str,
+        help="Target network interface",
+    )
+    p.add_argument(
+        "-b",
+        "--broadcast-port",
+        env_var="BDCAST_PORT",
+        default=5076,
+        type=int,
+        help="Port on which to receive and transmit UDP broadcasts",
+    )
+    p.add_argument(
+        "-m",
+        "--mesh-port",
+        env_var="MESH_PORT",
+        default=7124,
+        type=int,
+        help="Port on which this instance will communicate with others via UDP unicast",
+    )
+    p.add_argument(
+        "--other-relays",
+        nargs="+",
+        type=str,
+        default=[],
+        help="Manually select other relays to transmit received UDP broadcasts to",
+    )
+    p.add_argument(
+        "-ll",
+        "--log-level",
+        env_var="LOGLEVEL",
+        choices=["debug", "info", "warning", "error", "critical"],
+        default="info",
+        help="Logging level",
+    )
+    # Remember to add new arguments to the Args class above!
+
+    # config = p.parse_args(argv)
+    config = ConfigArgs(**p.parse_args(argv).__dict__)
+
+    match config.log_level:
+        case "critical":
+            loglevel = logging.CRITICAL
+        case "error":
+            loglevel = logging.ERROR
+        case "warning":
+            loglevel = logging.WARNING
+        case "info":
+            loglevel = logging.INFO
+        case "debug":
+            loglevel = logging.DEBUG
+
+    if loglevel < logging.INFO:
+        logging.basicConfig(
+            format="%(asctime)s - %(levelname)s - " "%(name)s.%(funcName)s: %(message)s",
+            encoding="utf-8",
+            level=loglevel,
+        )
+    else:
+        logging.basicConfig(format="%(asctime)s - %(levelname)s: %(message)s", encoding="utf-8", level=loglevel)
+
+    if config.broadcast_port == config.mesh_port:
+        # Can't use the same port for two different purposes
+        # Later, if we allow the receive relay and transmit relay on different
+        # ports we may need to revisit this error
+        logger.error(
+            "Broadcast port (%i) and mesh port (%i) may not be the same", config.broadcast_port, config.mesh_port
+        )
+        raise ValueError(
+            f"Broadcast port ({config.broadcast_port}) and " f"mesh port ({config.mesh_port}) may not be the same"
+        )
+
+    return config

snowsignal/dockerfile

@@ -0,0 +1,9 @@
+# Use slim because if we used alpine we'd need gcc for the 
+# psutils requirement in requirements.txt
+FROM python:3.12-slim
+
+# Token has read_api and read_repository permissions and so does not need to be kept secret
+# However it will expire
+RUN pip install SnowSignal --index-url https://gitlab.stfc.ac.uk/api/v4/projects/5671/packages/pypi/simple 
+
+CMD ["python", "-m", "snowsignal"]

snowsignal/netutils.py

@@ -0,0 +1,137 @@
+"""Network related utility functions for SnowSignal"""
+
+import ipaddress
+import logging
+import socket
+import sys
+
+import psutil
+
+logger = logging.getLogger(__name__)
+
+# Explanation for repeated use of `pyl1nt: disable=no-member` in
+# this file: a "bug" in PyLint means that it incorrectly diagnoses
+# socket.AddressFamily as an error, since it believes that socket
+# has no attribute AddressFamily. So we suppress this incorrect error
+
+
+def get_ips_from_name(name: str) -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    """Given a hostname return its IP addresses as a list"""
+    local_ips_details = socket.getaddrinfo(f"{name}", 80)
+
+    ips = []
+    for local_ip_detail in local_ips_details:
+        addfamily = local_ip_detail[0]
+        if addfamily in (socket.AddressFamily.AF_INET6, socket.AddressFamily.AF_INET):  # pylint: disable=no-member
+            ip = ipaddress.ip_address(local_ip_detail[4][0])
+            ips.append(ip)
+        else:
+            raise RuntimeError(f"Unknown AddressFamily {addfamily}")
+
+    # Remove duplicates and return
+    ips = list(set(ips))
+
+    return ips
+
+
+def get_localhost_ips() -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    """Establish the IP address(es) of this container"""
+    # Note that in a Docker Swarm environment we expect the container to
+    # have at least two IP addresses, it's traditional IP address associated
+    # with eth0 but also a Virtual IP (VIP) shared with all of the
+    # other containers in the same task. We could also have other IP
+    # addresses associated with other networks. So there could be many
+    # IP addresses for this one container!
+
+    # This is a bit of a hack but is apparently the most portable way
+    local_ips = get_ips_from_name(socket.gethostname())
+    logger.debug("\tThis system has IP address(es) %s:", local_ips)
+
+    return local_ips
+
+
+class ResourceNotFoundException(OSError):
+    """Indicate an expected hardware resource could not be found"""
+
+
+def get_from_iface(
+    iface: str,
+    family: socket.AddressFamily | int,
+    attribute: str = "address",  # pylint: disable=no-member
+):
+    """Get the IP address associated with a network interface"""
+    snicaddrs = psutil.net_if_addrs()[iface]
+    for snicaddr in snicaddrs:
+        if snicaddr.family == family:
+            return getattr(snicaddr, attribute)
+
+    raise ResourceNotFoundException(
+        f"Could not identify the {family}, " "{attribute} associated with interface {iface}"
+    )
+
+
+def get_localipv4_from_iface(iface: str) -> str:
+    """Get the IPv4 address associated with a network interface"""
+    return get_from_iface(iface, socket.AddressFamily.AF_INET)  # pylint: disable=no-member
+
+
+def get_macaddress_from_iface(iface: str) -> str:
+    """Get the MAC address associated with a network interface"""
+    if sys.platform != "win32":
+        return get_from_iface(iface, socket.AddressFamily.AF_PACKET)  # pylint: disable=no-member
+    else:
+        return get_from_iface(iface, psutil.AF_LINK)
+
+
+def get_localhost_macs() -> list[str]:
+    """Get all the MAC addresses of local network interfaces"""
+    macs = []
+
+    ifaces = psutil.net_if_addrs()
+    for iface in ifaces:
+        try:
+            macs.append(get_macaddress_from_iface(iface))
+        except ResourceNotFoundException:
+            pass
+
+    return macs
+
+
+def get_broadcast_from_iface(iface: str) -> str:
+    """Get the MAC address associated with a network interface"""
+    broadcast_address = get_from_iface(iface, socket.AddressFamily.AF_INET, attribute="broadcast")  # pylint: disable=no-member
+
+    # If we don't get a valid broadcast address then attempt to substitute one
+    if not broadcast_address:
+        return "255.255.255.255"
+
+    return broadcast_address
+
+
+def human_readable_mac(macbytes: bytes, separator: str = ":") -> str:
+    """Convert MAC in bytes into human-readable string with separators"""
+    unseparated_mac_str = macbytes.hex()
+    return separator.join([i + j for i, j in zip(unseparated_mac_str[::2], unseparated_mac_str[1::2])])
+
+
+def machine_readable_mac(macstr: str) -> bytes:
+    """Convert MAC with ':' or '-' separators into bytes without seperators"""
+    hexstring = macstr.translate({45: "", 58: ""})
+    return bytes.fromhex(hexstring)
+
+
+def identify_pkttype(pkttype: int) -> str:
+    """Decode packet type from socket.recvfrom"""
+    match pkttype:
+        case socket.PACKET_HOST:
+            return "PACKET_HOST"
+        case socket.PACKET_BROADCAST:
+            return "PACKET_BROADCAST"
+        case socket.PACKET_MULTICAST:
+            return "PACKET_MULTICAST"
+        case socket.PACKET_OTHERHOST:
+            return "PACKET_OTHERHOST"
+        case socket.PACKET_OUTGOING:
+            return "PACKET_OUTGOING"
+        case _:
+            return "UNKNOWN PACKET TYPE"

snowsignal/packet.py

@@ -0,0 +1,174 @@
+"""Simplified model of a Ethernet / IP / UDP packet"""
+
+import dataclasses
+import logging
+import socket
+from enum import Enum, unique
+from struct import unpack
+
+logger = logging.getLogger(__name__)
+
+
+ETH_LENGTH = 14
+
+
+@unique
+class EthernetProtocol(Enum):
+    """Meaning of protocol value from Ethernet frame header"""
+
+    UNKNOWN = 0  # We could classify more but we don't care!
+    IPv4 = 0x0800  # pylint: disable=invalid-name
+    IPv6 = 0x86DD  # pylint: disable=invalid-name
+
+    @classmethod
+    def _missing_(cls, _):
+        return cls.UNKNOWN
+
+
+class BadPacketException(Exception):
+    """Basic exception type raised by Packet class"""
+
+
+@dataclasses.dataclass
+class Packet:
+    """How to deconstruct and modify a Ethernet / UDP Packet
+    This is a very limited implementation designed only to support the
+    operations needed by this code. For example, it does not attempt to
+    recompute the checksums if the payload is modified."""
+
+    raw: bytes
+
+    eth_protocol: EthernetProtocol = EthernetProtocol.UNKNOWN
+    eth_dst_mac: bytes | None = None
+    eth_src_mac: bytes | None = None
+
+    _iph_length: int = dataclasses.field(default=-1, repr=False)
+    ip_version: int | None = None
+    ip_protocol: int | None = None
+    ip_chksum: int | None = None
+    ip_src_addr: str | None = None
+    ip_dst_addr: str | None = None
+
+    udp_src_port: int | None = None
+    udp_dst_port: int | None = None
+    udp_length: int | None = None
+    udp_chksum: int | None = None
+
+    def __post_init__(self) -> None:
+        # Always decode the Ethernet portion, but we're lazy about
+        # decoding the higher protocols
+        self.decode_ethernet()
+
+    def decode_ethernet(self) -> None:
+        """Interpret input bytes as a Ethernet packet"""
+        # https://en.wikipedia.org/wiki/Ethernet_frame#Structure
+
+        logger.debug("Decoding ethernet packet %r", self.raw)
+
+        try:
+            # TODO: Do we need to account for formats other than Ethernet-II or
+            # VPN frames, etc.
+            eth_header = self.raw[:ETH_LENGTH]
+            eth = unpack("!6s6sH", eth_header)
+
+            self.eth_protocol = EthernetProtocol(eth[2])
+            self.eth_dst_mac = eth[0]
+            self.eth_src_mac = eth[1]
+        except Exception as e:
+            raise BadPacketException from e
+
+    def _decode_ipv4(self) -> None:
+        """Decode IPv4 protocol header"""
+        # https://en.wikipedia.org/wiki/IPv4#Packet_structure
+        # Take the data for the IPv4 header from the packet
+        ip_header = self.raw[ETH_LENGTH : 20 + ETH_LENGTH]  # noqa: E203
+
+        # Unpack data from IP header
+        iph = unpack("!BBHHHBBH4s4s", ip_header)
+
+        # Calculate the version
+        version_ihl = iph[0]
+        self.ip_version = version_ihl >> 4
+
+        if self.ip_version != 4:
+            return
+
+        # Calculate the length (of the header?)
+        ihl = version_ihl & 0xF
+        self._iph_length = ihl * 4
+
+        # ttl = iph[5] # Time to live
+        self.ip_protocol = iph[6]
+        self.ip_chksum = iph[7]
+        self.ip_src_addr = socket.inet_ntoa(iph[8])
+        self.ip_dst_addr = socket.inet_ntoa(iph[9])
+
+    def _decode_ipv6(self) -> None:
+        """Decode IPv6 protocol header"""
+        # https://en.wikipedia.org/wiki/IPv6_packet#Fixed_header
+        ip_header = self.raw[ETH_LENGTH : 40 + ETH_LENGTH]  # noqa: E203
+
+        # Unpack data from IP header
+        iph = unpack("!IHBB16s16s", ip_header)
+
+        # Calculate the version
+        version_ihl = ip_header[0]
+        self.ip_version = version_ihl >> 4
+
+        if self.ip_version != 6:
+            return
+
+        # Calculate the length of the header
+        self._iph_length = 40  # IPv6 header is a fixed length
+
+        self.ip_protocol = iph[2]
+        self.ip_chksum = None  # IPv6 relies on other layers for the checksum
+        self.ip_src_addr = iph[4]
+        self.ip_dst_addr = iph[5]
+
+    def decode_ip(self) -> None:
+        """Decode the IP Protocol header"""
+        try:
+            match self.eth_protocol:
+                case EthernetProtocol.IPv4:
+                    self._decode_ipv4()
+                case EthernetProtocol.IPv6:
+                    self._decode_ipv6()
+                case EthernetProtocol.UNKNOWN:
+                    # If we don't know what this is then do nothing
+                    return
+                case _:
+                    # This ought to be impossible so we will raise in this case
+                    raise SyntaxError(f"Unhandled ip_protocol type {self.eth_protocol}")
+        except Exception as e:
+            raise BadPacketException from e
+
+    def decode_udp(self) -> None:
+        """Decode UDP header information"""
+        try:
+            # Get the UDP Header
+            udp_packet_start = self._iph_length + ETH_LENGTH
+            udp_packet_end = udp_packet_start + 8
+            udp_header = self.raw[udp_packet_start:udp_packet_end]
+
+            # now unpack them :)
+            udph = unpack("!HHHH", udp_header)
+
+            self.udp_src_port = udph[0]
+            self.udp_dst_port = udph[1]
+            self.udp_length = udph[2]
+            self.udp_chksum = udph[3]
+        except Exception as e:
+            raise BadPacketException from e
+
+    def get_udp_payload(self) -> bytes:
+        """Get the UDP payload from the packet"""
+        try:
+            udp_packet_end = self._iph_length + ETH_LENGTH + 8
+            return self.raw[udp_packet_end:]
+        except Exception as e:
+            raise BadPacketException from e
+
+    def change_ethernet_source(self, newmac) -> None:
+        """Change packet Ethernet source to a new MAC address"""
+        self.raw = self.raw[0:6] + newmac + self.raw[12:]

snowsignal/snowsignal.py

@@ -0,0 +1,130 @@
+"""SnowSignal - UDP Broadcast Relay"""
+
+import asyncio
+import ipaddress
+import logging
+import os
+import sys
+from collections.abc import Sequence
+
+from .configure import ConfigArgs, configure
+from .netutils import get_ips_from_name, get_localhost_ips, get_localipv4_from_iface
+from .udp_relay_receive import UDPRelayReceive
+from .udp_relay_transmit import UDPRelayTransmit
+
+# Logging and configuration of Scapy
+logger = logging.getLogger()
+
+
+def is_swarmmode() -> bool:
+    """Crude check to see if we're running in docker swarm"""
+
+    swarmmode = False
+    try:
+        if os.environ["SERVICENAME"]:
+            swarmmode = True
+    except KeyError:
+        pass  # Docker Swarm related environment variable not set
+    return swarmmode
+
+
+def setup_remote_relays(
+    config: ConfigArgs, local_addr: str | ipaddress.IPv4Address | ipaddress.IPv6Address, swarmmode: bool
+) -> Sequence[str | ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    """Initial setup of the remote relays. If we're not in a Docker Swarm then
+    this is largely immutable."""
+
+    if swarmmode and not config.other_relays:
+        # Use swarm DNS magic to identify the other nodes
+        logger.debug("Using swarm DNS to identify other relays")
+        remote_relays = discover_relays()
+    elif not swarmmode and config.other_relays:
+        logger.debug("Using user configuration of other relays")
+        remote_relays = config.other_relays
+    else:
+        # Assume we're in testing mode and loopback to ourselves
+        logger.debug("Using debug mode for other relays, will relay to self")
+        remote_relays = [local_addr]
+    return remote_relays
+
+
+def discover_relays() -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    """Discover the other UDP Broadcast Relays in the stack"""
+
+    logger.debug("Beginning relay discovery")
+    # Establish the IP address(es) of this container
+    # This is a bit of a hack but is apparently the most portable way
+    local_ips = get_localhost_ips()
+
+    # Get the list of IP addresses in this stack
+    # First get the environment variable we're using to identify our stack
+    try:
+        stack_and_task = os.environ["SERVICENAME"]
+    except KeyError:
+        logger.critical("Environment variable SERVICENAME must be set as {{.Service.Name}} in compose file")
+        raise
+
+    # The important bit here is to query tasks. This will work however the
+    # endpoint_mode is set and will only list the other containers and not
+    # include the Virtual IP (VIP)
+    task_ips = get_ips_from_name(f"tasks.{stack_and_task}")
+    logger.debug("\tTasks in %s have IP address(es) %s:", stack_and_task, task_ips)
+
+    # We don't want to communicate with ourself
+    valid_ips = list(set(task_ips) - set(local_ips))
+    logger.info("\tDiscovered relays: %s", valid_ips)
+
+    return valid_ips
+
+
+# Weird "argv" syntax required to support unittests
+async def main(argv: Sequence[str] | None = None, loop_forever: bool = True):
+    """Main function
+    Load up the configuration and do some other setup. But mostly we're here
+    to start two asyncio tasks. One listens for UDP broadcasts and sends them
+    on to other relays. The other listens to the other relays and rebroadcasts
+    as they instruct. Then we sit in an infinite loop to allow these things to
+    happen!
+    """
+
+    # Configure this relay
+    config = configure(argv)
+    logger.info("Starting with configuration %s", config)
+
+    # Get the local IP address
+    # TODO: Properly support IPv6
+    local_addr = get_localipv4_from_iface(config.target_interface)
+
+    # Check if we're running in a Docker Swarm
+    swarmmode = is_swarmmode()
+
+    # Identify the remote relays to send UDP broadcasts messages to
+    remote_relays = setup_remote_relays(config, local_addr, swarmmode)
+
+    # Start listening for UDP broadcasts to transmit to the other relays
+    udp_relay_transmit = UDPRelayTransmit(
+        remote_relays=remote_relays, local_port=config.broadcast_port, remote_port=config.mesh_port, config=config
+    )
+    asyncio.create_task(udp_relay_transmit.start())
+
+    # Listen for messages from the other relays to UDP broadcast
+    udp_relay_receive = UDPRelayReceive(
+        local_addr=(local_addr, config.mesh_port), broadcast_port=config.broadcast_port, config=config
+    )
+    asyncio.create_task(udp_relay_receive.start())
+
+    # Loop forever, but if in swarm mode periodically recheck the relays
+    while loop_forever:
+        await asyncio.sleep(10)
+        if swarmmode:
+            # Check to see if remote relays have changed
+            # e.g. containers have restarted
+            udp_relay_transmit.set_remote_relays(discover_relays())
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logger.debug("Stopped by KeyboardInterrupt")
+        sys.exit(1)

snowsignal/udp_relay_receive.py

@@ -0,0 +1,196 @@
+"""
+Listen for UDP broadcasts on a port and transmit packet information to other relays
+
+This uses the standard asyncio.DatagramProtocol base class so most of the initial
+management of the UDP packet is already done for us.
+"""
+
+import array
+import asyncio
+import ipaddress
+import logging
+import socket
+import struct
+from copy import deepcopy
+from typing import Any
+
+from .configure import ConfigArgs
+from .netutils import get_broadcast_from_iface, get_macaddress_from_iface
+
+logger = logging.getLogger(__name__)
+
+
+class UDPRelayReceive(asyncio.DatagramProtocol):
+    """Listen to UDP messages from remote relays and forward them as broadcasts on the local net"""
+
+    def __init__(
+        self,
+        local_addr: tuple[ipaddress.IPv4Address | ipaddress.IPv6Address | str, int],
+        broadcast_port: int,
+        config: ConfigArgs | None = None,
+    ) -> None:
+        super().__init__()
+
+        self.local_addr = (str(local_addr[0]), local_addr[1])  # Get typing right
+        self.broadcast_port = broadcast_port
+        self.transport: asyncio.DatagramTransport
+        self._rebroad_sock: socket.socket
+
+        if config:
+            self._iface = config.target_interface
+        else:
+            self._iface = "eth0"
+
+        # Assume the MAC address is immutable
+        self._mac = get_macaddress_from_iface(self._iface)
+
+        # Also assume the broadcast address associated with the
+        # interface is immutable
+        self._broadcast_addr = get_broadcast_from_iface(self._iface)
+
+        # A way to manage the forever loop for unit testing and other purposes
+        self._loop_forever = True
+
+    def connection_made(self, transport: asyncio.DatagramTransport) -> None:
+        """Handle a connection being established"""
+        self.transport = transport
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        """Handle a connection being lost"""
+        # What does connection lost even mean for UDP?
+        # Seems only necessary to stop some spurious errors on server shutdown
+
+    def recalculate_udp_checksum(self, ip_packet) -> bytes:
+        """Calculate UDP checksum, using the IP and UDP parts of the packet,
+        and change the existing packet UDP checksum with the newly calculcated
+        checksum"""
+
+        # The UDP checksum algorithm is defined in RFC768
+        # https://www.rfc-editor.org/rfc/rfc768.txt
+        # "Checksum is the 16-bit one's complement of the one's complement sum of a
+        #  pseudo header of information from the IP header, the UDP header, and the
+        #  data, padded with zero octets at the end (if necessary) to make a
+        #  multiple of two octets"
+
+        # Extract the data needed to form the pseudo packet and header
+        # Got this from https://dev.to/cwprogram/python-networking-tcp-and-udp-4i3l
+
+        # Make a deepcopy of the UDP portion of the whole ip_packet so that we don't
+        # accidentally modify it. Then zero the part that contains the UDP checksum.
+        # A zero checksum is valid but we'll calculate the correct value
+        pseudo_packet = bytearray(deepcopy(ip_packet[20:]))
+        pseudo_packet[6] = 0x0
+        pseudo_packet[7] = 0x0
+
+        # We need information from the IP header to construct the pseudo-header
+        # needed in turn to calculate the UDP checksum. Specifically we need the
+        # source and destination IP addresses
+        ip_header = struct.unpack("!BBHHHBBH4s4s", ip_packet[0:20])
+        pseudo_header = struct.pack("!4s4sHH", ip_header[8], ip_header[9], socket.IPPROTO_UDP, len(pseudo_packet))
+
+        # Combine the pseudo header and pseudo packet to form a complete pseudo packet
+        # that we'll perform the checksum calculations on
+        checksum_packet = pseudo_header + pseudo_packet
+
+        # If there is an odd number of bytes in the checksum packet we need to
+        # pad it to an even number of bytes
+        if len(checksum_packet) % 2 == 1:
+            checksum_packet += b"\0"
+
+        # The checksum calculation proceeds by summing the one’s complement where
+        # all binary 0s become 1s, of all 16-bit words in these components.
+        onecompsum = sum(array.array("H", checksum_packet))
+        onecompsum = (onecompsum >> 16) + (onecompsum & 0xFFFF)
+        onecompsum += onecompsum >> 16
+        onecompsum = ~onecompsum  # Finally invert the bits
+
+        # Test endianness and do some magic if we're on a little endian system
+        if struct.pack("H", 1) != b"\x00\x01":
+            onecompsum = ((onecompsum >> 8) & 0xFF) | onecompsum << 8
+
+        # If checksum is 0 change it to 0xFFFF to signal it has been calculated
+        udp_checksum = onecompsum & 0xFFFF
+
+        # Insert the calculated checksum into the IP + UDP packet
+        ip_packet = ip_packet[:26] + udp_checksum.to_bytes(2, "big") + ip_packet[28:]
+
+        return ip_packet
+
+    def datagram_received(self, data: bytes, addr: tuple[str | Any, int]) -> None:
+        """Receive a UDP message and forward it to the remote relays"""
+        logger.debug(
+            "Received from %s for rebroadcast on port %i message: %r",
+            addr,
+            self.broadcast_port,
+            data,
+        )
+
+        # Simple verification of the received payload, and remove the bytes
+        # confirming that this is for us
+        if data[0:2] == b"SS":
+            data = data[2:]
+        else:
+            logger.debug("Malformed packet received")
+            return
+
+        # TODO: Apply any filters
+
+        # We can't use the data as is for some reason but need to recalculate the
+        # UDP checksum. We also remove the ethernet frame as the sendto() below
+        # will take care of that part
+        data = self.recalculate_udp_checksum(data[14:])
+
+        # TODO: The code above does not change the IP source address
+        # If we're on a different network segment then we should switch the
+        # broadcast IP address to use get_broadcast_from_iface(). This will
+        # then require recomputing checksums. Note: is this required? We
+        # are sending to the broadcast address in the sendto() below
+
+        # TODO: Logic to validate what we're receiving as a PVAccess message
+        # Note that although doing the validation on receipt means we're doing
+        # it for every relay (instead of once if we did it on send), it's much
+        # safer to do it on receipt since it means we don't have to trust the
+        # sender as much
+
+        # TODO: We should be using self.transport.sendto() in order to make
+        # this asynchronous but unfortunately that wouldn't allow us to
+        # control the IP headers. Is there another way to resolve that?
+
+        # Finally broadcast the new packet
+        # It doesn't feel much simpler but we're not using fully raw sockets here
+        # but instead letting Python do the work of handling the Ethernet frames
+        sendbytes = self._rebroad_sock.sendto(data, (self._broadcast_addr, self.broadcast_port))
+        logger.debug("Broadcast UDP packet of length %d on iface %s: %s", sendbytes, self._iface, data)
+
+    async def start(self) -> None:
+        """Start the UDP server that listens for messages from other relays and broadcasts them"""
+
+        logger.info(
+            "Starting UDP server listening on %s; will rebroadcast on port %i",
+            self.local_addr,
+            self.broadcast_port,
+        )
+
+        # Open the socket we'll rebroadcast messages on
+        self._rebroad_sock = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_UDP)
+        self._rebroad_sock.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, True)
+        self._rebroad_sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, True)
+        self._rebroad_sock.setblocking(False)
+
+        # Get a reference to the event loop as we plan to use
+        # low-level APIs.
+        loop = asyncio.get_running_loop()
+
+        # One protocol instance will be created to serve all
+        # client requests.
+        transport, _ = await loop.create_datagram_endpoint(
+            lambda: self, local_addr=self.local_addr, allow_broadcast=True
+        )
+
+        try:
+            while self._loop_forever:
+                # Basically sleep forever!
+                await asyncio.sleep(1)
+        finally:
+            transport.close()
+            self._rebroad_sock.close()

snowsignal/udp_relay_transmit.py

@@ -0,0 +1,221 @@
+"""
+The UDPRelayTransmit class is confusingly named. It transmits packets
+into the relay mesh network. That means that it is also the class that
+listens for UDP broadcasts on the specified network interface and port.
+
+It applies a number of defined filters (level 1 to level 4) to verify
+that the received packet was received on the specified network interface,
+port, that it is a broadcast packet, and that it is a well-formed UDP packet.
+Importantly it filters out any packets that were received from this network
+interfaces MAC address.
+
+If these criteria are met then it sends the packet to the rest of the mesh
+network relays.
+"""
+
+import asyncio
+import ipaddress
+import logging
+import socket
+from collections.abc import Sequence
+
+from .configure import ConfigArgs
+from .netutils import get_localhost_macs, human_readable_mac, identify_pkttype, machine_readable_mac
+from .packet import BadPacketException, EthernetProtocol, Packet
+
+logger = logging.getLogger(__name__)
+
+
+class UDPRelayTransmit:
+    """Listen for UDP broadcasts and transmit to the other relays"""
+
+    def __init__(
+        self,
+        remote_relays: Sequence[ipaddress.IPv4Address | ipaddress.IPv6Address | str],
+        local_port: int = 5076,
+        remote_port: int = 7124,
+        config: ConfigArgs | None = None,
+    ) -> None:
+        self._loop_forever = True
+
+        logger.info(
+            "Initialising UDPRelayTransmit listening for UDP broadcasts "
+            "on port %i for relay to remote relays %s on port %i",
+            local_port,
+            remote_relays,
+            remote_port,
+        )
+
+        self.local_port = local_port
+        self.remote_port = remote_port
+        self.remote_relays = remote_relays
+
+        # If there's a config provided then use the setting from it,
+        # otherwise use some sensible defaults
+        if config:
+            self._iface = config.target_interface
+        else:
+            self._iface = "eth0"
+
+        self._macs = get_localhost_macs()
+        self._macs = [machine_readable_mac(x) for x in self._macs]
+        self.ip_whitelist = []  # NotImplemented
+
+    async def _send_to_relays_packet(self, packet: Packet) -> None:
+        """
+        Callback to send whole packet to other relays
+        if packet passes sniffer filters
+        """
+        logger.debug("Transmitting to relays UDP broadcast message:\n%s", packet)
+
+        pkt_raw = b"SS" + packet.raw
+
+        await self._send_to_relays_bytes(pkt_raw)
+
+    async def _send_to_relays_bytes(self, msgbytes: bytes) -> None:
+        """Send bytes to the remote relays"""
+
+        for remote_relay in self.remote_relays:
+            logger.debug(
+                "Send to (%s, %i) message: %r",
+                remote_relay,
+                self.remote_port,
+                msgbytes,
+            )
+            sock_family = socket.AF_INET
+            if isinstance(remote_relay, ipaddress.IPv6Address):
+                sock_family = socket.AF_INET6
+
+            with socket.socket(sock_family, socket.SOCK_DGRAM) as s:
+                s.setblocking(False)
+                loop = asyncio.get_running_loop()
+                await loop.sock_sendto(s, msgbytes, (str(remote_relay), self.remote_port))
+
+    def l1filter(self, ifname: str) -> bool:
+        """Check the network interface is as expected"""
+        if ifname != self._iface:
+            logger.debug("Identified as using wrong iface %s", ifname)
+            return False
+
+        return True
+
+    def l2filter(self, packet: Packet) -> bool:
+        """Tests to perform on Level2 of packet, i.e. Ethernet"""
+        # Make sure this is a broadcast and that its payload is an IP protocol message
+        if packet.eth_dst_mac != b"\xff\xff\xff\xff\xff\xff":
+            logger.debug("Not broadcast packet %r", packet)
+            return False
+        if packet.eth_protocol == EthernetProtocol.UNKNOWN:
+            logger.debug("Not known ethernet protocol packet %r", packet)
+            return False
+
+        # Do not process packets sourced from this machine
+        if packet.eth_src_mac in self._macs:
+            logger.debug("Source is a local MAC")
+            return False
+
+        return True
+
+    def l3filter(self, packet: Packet) -> bool:
+        """Tests to perform on Level3 of packet, i.e IP Protocol"""
+
+        # Make sure this contains a UDP payload
+        if packet.ip_protocol != 17:  # 17 is UDP
+            return False
+
+        # If we have a whitelist of source addresses then check it claims to come
+        # from one of them
+        if self.ip_whitelist:
+            if packet.ip_src_addr not in self.ip_whitelist:
+                return False
+
+        return True
+
+    def l4filter(self, packet: Packet) -> bool:
+        """Tests to perform on Level4 of packet, i.e. UDP Protocol"""
+        if packet.udp_dst_port != self.local_port:
+            logger.debug("Wrong UDP destination port: %i", packet.udp_dst_port)
+            return False
+
+        return True
+
+    async def start(self) -> None:
+        """Monitor for UDP broadcasts on the specified port"""
+        # create a AF_PACKET type raw socket (thats basically packet level)
+        # define ETH_P_ALL    0x0003          /* Every packet (be careful!!!) */
+        # define ETH_P_IP     0x0800          IP packets only; I believe this is IPv4
+        with socket.socket(
+            socket.AF_PACKET,
+            socket.SOCK_RAW,
+            socket.ntohs(0x0800),  # pylint: disable=no-member
+        ) as sock:
+            sock.setblocking(False)
+
+            while self._loop_forever:
+                loop = asyncio.get_running_loop()
+
+                raw_packet = await loop.sock_recvfrom(sock, 1024)
+                (ifname, proto, pkttype, hatype, addr) = raw_packet[1]
+                raw_packet = raw_packet[0]
+                logger.debug(
+                    "Received on iface %s (proto %r, pktytype %r, hatype %r, addr %r) data %r",
+                    ifname,
+                    socket.ntohs(proto),
+                    identify_pkttype(pkttype),
+                    socket.ntohs(hatype),
+                    human_readable_mac(addr),
+                    raw_packet,
+                )
+
+                try:
+                    # Check Level 1 physical layer, i.e. network interface
+                    if not self.l1filter(ifname):
+                        logger.debug("Failed l1filter")
+                        self._loop_forever = self._continue_while_loop()
+                        continue
+
+                    # Check Level 2 data link layer, i.e. ethernet header
+                    packet = Packet(raw_packet)
+                    if not self.l2filter(packet):
+                        logger.debug("Failed l2filter")
+                        self._loop_forever = self._continue_while_loop()
+                        continue
+
+                    # Check Level 3 network layer, i.e. IP protocol
+                    packet.decode_ip()
+                    if not self.l3filter(packet):
+                        logger.debug("Failed l3filter")
+                        self._loop_forever = self._continue_while_loop()
+                        continue
+
+                    # Check Level 4 transport protocol, i.e. UDP
+                    packet.decode_udp()
+                    if not self.l4filter(packet):
+                        logger.debug("Failed l4filter")
+                        self._loop_forever = self._continue_while_loop()
+                        continue
+                except BadPacketException as bpe:
+                    logger.debug("Malformed packet %r", bpe)
+                    self._loop_forever = self._continue_while_loop()
+                    continue
+
+                # Send to other relays
+                await self._send_to_relays_packet(packet)
+                self._loop_forever = self._continue_while_loop()
+
+    def _continue_while_loop(self) -> bool:
+        """This function exists purely to allow unit testing of the start() function above"""
+        return self._loop_forever
+
+    def stop(self) -> None:
+        """Stop the main event loop in the start function"""
+        self._loop_forever = False
+
+    def set_remote_relays(self, remote_relays: list[ipaddress.IPv4Address | ipaddress.IPv6Address]) -> None:
+        """Update the list of remote relays"""
+        # We check if there's a change because although it shouldn't much
+        # matter if there's a race condition from making a change we might
+        # as well minimise the risk anyway
+        if remote_relays != self.remote_relays:
+            logger.info("Updating remote relays, will use %s", remote_relays)
+            self.remote_relays = remote_relays

snowsignal-0.1.1.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.3
+Name: SnowSignal
+Version: 0.1.1
+Summary: UDP Broadcast Relay
+Project-URL: Repository, https://github.com/ISISNeutronMuon/SnowSignal
+Author-email: Ivan Finch <ivan.finch@stfc.ac.uk>
+Maintainer-email: Ivan Finch <ivan.finch@stfc.ac.uk>
+License-File: LICENSE
+Keywords: UDP,UDP broadcast,docker swarm,epics,pvaccess
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: configargparse>=1.7
+Requires-Dist: psutil>=5.9
+Provides-Extra: dist
+Requires-Dist: build>=1.2; extra == 'dist'
+Requires-Dist: twine>=5.1; extra == 'dist'
+Provides-Extra: test
+Requires-Dist: coverage>=7.6; extra == 'test'
+Requires-Dist: ruff>0.6; extra == 'test'
+Requires-Dist: scapy~=2.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# SnowSignal
+SnowSignal is designed to create a mesh network between instances of the program that will listen for UDP broadcasts received on one node of the network and rebroadcast on all other nodes.
+
+
+[![pipeline status](https://gitlab.stfc.ac.uk/isis-accelerator-controls/playground/ivan/infrastructure/snowsignal/badges/main/pipeline.svg)](https://gitlab.stfc.ac.uk/isis-accelerator-controls/playground/ivan/infrastructure/snowsignal/-/commits/main) 
+[![coverage report](https://gitlab.stfc.ac.uk/isis-accelerator-controls/playground/ivan/infrastructure/snowsignal/badges/main/coverage.svg)](https://gitlab.stfc.ac.uk/isis-accelerator-controls/playground/ivan/infrastructure/snowsignal/-/commits/main)
+
+[[_TOC_]]
+
+## Usage
+### General
+Command line and environment variable options. Environment variables are defined in square brackets like `[env var: THIS]`. In general, command-line values override environment variables which override defaults.
+``` 
+usage: snowsignal.py [-h] [-t TARGET_INTERFACE] [-b BROADCAST_PORT] [-m MESH_PORT]
+                     [--other-relays OTHER_RELAYS [OTHER_RELAYS ...]]
+                     [-l {debug,info,warning,error,critical}]
+```
+#### Target Interface
+```
+  -t TARGET_INTERFACE, --target-interface TARGET_INTERFACE
+                        Target network interface [env var: TARGET_INTERFACE]
+```
+At this time SnowSignal only supports using a single network interface for receiving UDP broadcasts, sending to other relays, and rebroadcasting UDP messages received from other relays.
+Defaults to `eth0`.
+
+#### Broadcast Port
+```
+  -b BROADCAST_PORT, --broadcast-port BROADCAST_PORT
+                        Port on which to receive and transmit UDP broadcasts [env var: BDCAST_PORT]
+```
+SnowSignal listens for UDP broadcasts on a single port and rebroadcasts messages received from other SnowSignal instances on the same port. Defaults to port 5076.
+
+#### Mesh Port
+```
+  -m MESH_PORT, --mesh-port MESH_PORT
+                        Port on which this instance will communicate with others via UDP unicast [env var:
+                        MESH_PORT]
+```
+UDP port on which to listen for messages from other SnowSignal instances. Defaults to port 7124.
+
+#### Other relays
+```
+  --other-relays OTHER_RELAYS [OTHER_RELAYS ...]
+                        Manually select other relays to transmit received UDP broadcasts to
+```
+Manually set a list of other SnowSignal instances with which to communicate. In Docker Swarm SnowSingal is capable of auto-discovering instances if the `SERVICENAME` environment variable is set, see "Mesh Network" below. If no other relays are defined via any of these means then SnowSignal will communicate with itself for testing purposes. Default is an empty list.
+
+#### Log Level
+```
+  -ll {debug,info,warning,error,critical}, --log-level {debug,info,warning,error,critical}
+                        Logging level [env var: LOGLEVEL]
+```
+Set the logging level.
+
+### Docker Swarm
+If run in a Docker Swarm then the default configuration should work well with PVAccess. 
+
+There is an additional requirement that the environment variable SERVICENAME be set with the Swarm service's name, e.g. 
+```
+    environment:
+      SERVICENAME: '{{.Service.Name}}'
+```
+
+This allows each node in the service to automatically located and connect to the other nodes. The mesh will automatically heal as members enter and leave.
+
+### Limitations ###
+At this time this code has only been tested in Linux containers.
+
+The `UDPRelayTransmit` class requires a raw socket to operate as it needs to 
+1. Filter out UDP broadcasts with an Ethernet source originating from the local relay. The Ethernet source is rewritten to allow this filtering while the IP source is left alone.
+2. Differentiate UDP broadcast from UDP unicast messages, ignoring the latter.
+
+These require Level 1 and 2 access and thus raw sockets. As the Python socket package does not support such access on Windows it has not been possible to make this tool compatible with that OS. (An earlier version using ScaPy was compatible.)
+
+## The Problem
+The EPICS PVAccess protocol uses a mixture of UDP broadcast, UDP unicast and TCP (in roughly that order) to establish communication between a client and a server. In the case relevant to this package a client makes a query for a PV and its value (or some other field), e.g. a pvget while the server holds the requested PV.
+
+The image below gives an example of the communication between a client and server and is taken from the [PVAccess Protocol Specification](https://epics-controls.org/wp-content/uploads/2018/10/pvAccess-Protocol-Specification.pdf). 
+
+![PVAccess protocol specification communication example](docs/pvacess_communication_example.png)
+
+The relevant part for this problem is the initial searchRequest - a UDP broadcast / multicast. (Although the specification requires multicast support at this time I have only ever seen broadcast used.) When a pvget (or equivalent) is performed the first step is a UDP broadcast search request, i.e. a cry to local machines asking if they have the requested PV. If any do they will reply back to the requesting process with a UDP unicast and establish a TCP connection to exchange information.
+
+UDP broadcasts are restricted to the network segment of the network interface conducting the broadcast. This means that search requests will not reach machines not on the same network segment. Alternative means suchs as a PVA Gateway or `EPICS_PVA_NAME_SERVERS` must be used in such circumstances. Note that 
+-  PVA Gateway allows communication between isolated network segments but all subsequent communications must pass through the Gateway, i.e. a many to one to many topology is implicitly created.
+- `EPICS_PVA_NAME_SERVERS` requires only that TCP communication between server and client be possible, but requires servers to be specified in advance.
+
+However, if unicast communication between two network segments is possible then we could simply relay the UDP broadcasts between the two networks, allowing UDP unicast and TCP communication to proceed as usual.
+
+This is the purpose of SnowSignal. It relays UDP broadcasts received on a specified port to other instances of SnowSignal (i.e. forming a mesh network) that then rebroadcast those UDP broadcasts on their own network segments.
+
+**Note**: PVAccess server UDP beacon messages also use UDP broadcast and will be relayed by SnowSignal. Their purpose and consequences is not explored further here.
+
+### Docker Swarm and Docker Networks
+A docker swarm network may be created which crosses transparently between the nodes in the swarm. However, at the time of writing, docker swarm networks do not support UDP multicast or broadcast. 
+
+For PVAccess this means that search requests are isolated to individual nodes in the swarm. A pvget to a server-container on the same node will succeed, while one to a server-container on another node will fail. (Assuming that PVA Gateway or `EPICS_PVA_NAME_SERVERS` is not used to overcome this limitation.)
+
+## For Developers
+See details on using the [local dev setup](docs/local_dev.md) as well as discussion below.
+
+## Implementation
+SnowSignal is implemented in Python using base Python except for the libraries [ConfigArgParse](https://pypi.org/project/ConfigArgParse/) and [psutil](https://pypi.org/project/psutil/). The [scapy](https://scapy.readthedocs.io/en/latest/) library is used in integration and unit tests to create, send, receive, and manipulate UDP packets. 
+
+The SnowSignal code is in two main parts:
+
+### 1. udp_relay_transmit
+The UDPTransmitRelay class uses a raw socket to monitor for UDP broadcasts on the specified UDP port and local interface. A set of filter functions are used to filter out broadcasts either originating from local interfaces' MAC addresses or from the local IP addresses. This prevents us from reacting to our own UDP broadcasts.
+
+If a UDP broadcast packet passes the required filters then the whole packet is sent to the other SnowSignal instances in the mesh network. They will subsequently rebroadcast it.
+
+### 2. udp_relay_receive
+A UDPReceiveRelay class listens for UDP unicast messages received on a specified port and broadcasts those messages on a specified local interface. The class is an implementation of the asynchio [DatagramProtocol](https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols) run by using [loop.create_datagram_endpoint()](https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint). 
+
+When a UDP message is received from another SnowSignal its payload is turned into a UDP broadcast packet. We change only the Ethernet source MAC address of packet, setting it to that of the interface that will be used to send it. This means that it can be filtered out by the `udp_relay_transmit` and we do not create packet storms. 
+
+### Mesh Network
+The SnowSignal mesh network may be manually specified. 
+
+However, in a Docker Swarm environment we can identify the other services by using the DNS entries for `{{.Service.Name}}.tasks`. We then need only remove this nodes IP address from that list to get the other nodes in the mesh. We update the list of mesh nodes from this source every 10 seconds which allows us to accomodate container restarts or migrations and even, in theory, nodes entering and leaving the swarm.
+
+### Observations and Lessons Learned
+A number of issues arose as I was developing this utility: 
+- I originally attempted to be clever around preventing a UDP broadcast storm by using a hashes of the UDP packets broadcast by a node member and then rejecting broadcast messages that were subsequently received by the same node. (More specifically a time-to-live dictionary so that packets weren't banned forever.) This proved overly complex and the current implementation simply filters out UDP broadcasts with sources with the same MAC address as the individual nodes.
+- A PVAccess search request includes the IP address and ephemeral port that the unicast UDP reply should use. Experience shows that implementations ignore this in favour of the packet UDP source IP and port. This is why it's ultimately simpler to copy the whole packet and alter it rather than send the payload and construct a new packet around it.
+
+## Origin of Name
+A sensible name for this program would be UDP Broadcast Relay, e.g. UBrR. And brr is being cold. Hence with some helps from a name generator the name SnowSignal.

snowsignal-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+snowsignal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+snowsignal/__main__.py,sha256=AehSEZINUEFv4Y2zFjUHpBifeLZNE-KFA2X9vZ890LU,255
+snowsignal/configure.py,sha256=e_dLvanmrPVs6RG1KOZPzscRJF9SbYlwstDMqBJSU90,3180
+snowsignal/dockerfile,sha256=HeJUva1v8-QBjU_yd8NNPSo3YEDYLdHLiSkF3Yf-28Q,386
+snowsignal/netutils.py,sha256=ZQ0cs3JF0Ec1DRWQsLOaLEcBRx6iGK4A6EQITIPac84,4794
+snowsignal/packet.py,sha256=CNnFDpoFdtIwAMBenXrRrOK7UpHAGsOXlI1QOcSWyeM,5696
+snowsignal/snowsignal.py,sha256=bG8I6tiFTixTiRYtDGcETbfqbTwZTb_nVxYvZeCGmvo,4822
+snowsignal/udp_relay_receive.py,sha256=uySOhRKLd2L1epHXYUxHP6M_Ey6NQ4LcN7MKtbH5pdQ,8331
+snowsignal/udp_relay_transmit.py,sha256=gxdS1dVPB4srkRtNA_UPOz3jDZsbfZNjL68VF8DtFuU,8626
+snowsignal-0.1.1.dist-info/METADATA,sha256=PHJ9-4_asNKK_g_cjajA0bDFhSUi9aRHc3rfMXSy7fE,11507
+snowsignal-0.1.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+snowsignal-0.1.1.dist-info/licenses/LICENSE,sha256=Xyl-Ykl-HUYLhQ4bu65pmUbqf8c-deJjxoq7ScjEcrI,1526
+snowsignal-0.1.1.dist-info/RECORD,,

snowsignal-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

snowsignal-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,13 @@
+BSD 3-Clause License
+
+Copyright (c) 2024 Science and Technology Facilities Council (STFC), UK
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.