{"id":13735865,"url":"https://github.com/OpenSourceLAN/service-discovery-helper","last_synced_at":"2025-05-08T12:31:21.310Z","repository":{"id":10932362,"uuid":"13236846","full_name":"OpenSourceLAN/service-discovery-helper","owner":"OpenSourceLAN","description":"A simple tool to forward UDP broadcasts (eg, gameserver discovery) between networks. ","archived":false,"fork":false,"pushed_at":"2018-10-25T12:36:17.000Z","size":61,"stargazers_count":47,"open_issues_count":1,"forks_count":7,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-11-15T04:31:11.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenSourceLAN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-10-01T06:52:34.000Z","updated_at":"2024-09-10T18:20:25.000Z","dependencies_parsed_at":"2022-08-29T20:31:36.700Z","dependency_job_id":null,"html_url":"https://github.com/OpenSourceLAN/service-discovery-helper","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSourceLAN%2Fservice-discovery-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSourceLAN%2Fservice-discovery-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSourceLAN%2Fservice-discovery-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSourceLAN%2Fservice-discovery-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenSourceLAN","download_url":"https://codeload.github.com/OpenSourceLAN/service-discovery-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253068473,"owners_count":21848820,"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":[],"created_at":"2024-08-03T03:01:12.264Z","updated_at":"2025-05-08T12:31:21.037Z","avatar_url":"https://github.com/OpenSourceLAN.png","language":"C","funding_links":[],"categories":["Software"],"sub_categories":["Network-related software"],"readme":"\n\n# Service Discovery Helper\n##### A UDP Broadcast forwarder \n##### (c) Chris Holman, 2013\n\nIf you operate a network with more than one VLAN or LAN segment, then UDP broadcast discovery won't \n*just work* across your entire network. Enter, Service Discovery Helper (SDH).\n\nMany programs use UDP broadcasts to discover their servers/peers. SDH forwards these UDP broadcasts between \nnetworks, enabling discovery functionality where it would not usually work.\n\nSDH will listen on the specified network interfaces for UDP broadcasts on specified\nports and retransmit the packets on remaining network interfaces. It uses a whitelist\nfor UDP ports that it will forward, so you can be sure that you will not\naccidentally forward DHCP or SSDP to every other VLAN. \n\nThe use case that inspired this tool is large LAN parties, where you may have hundreds\n(or thousands!) of PCs on one network. Operating this many PCs on one broadcast domain \nintroduces a number of issues, and is considered probably not the best practice. \nThe normal solution to this is to segment the network in to a number of \nVLANs on their own subnet, such that there are a much smaller number of PCs in one \nbroadcast domain. But then game server discovery doesn't work!\n\nSee GAMES.md for a list of tested games. \n\n### Requirements\n\n* Linux (or maybe BSD or other \\*nix environment)\n* gcc or similar (apt-get install build-essential)\n* libpcap and libpcap-dev\n* Root privilges\n* 2 or more local network interfaces\n\n### Usage\n\nTrunk all of your VLANs to a PC somewhere. (Consult switch documentation)\n\n````\n sudo modprobe 8021q\n sudo ip link add link eth0 name eth0.2 type vlan id 2\n # Repeat for each VLAN you have\n # Edit the configuration files (ports and interfaces are the defaults)\n make \n sudo ./sdh-proxy [-p ports-file -i interfaces-file [-d] ] [-h] \n````\n\n\n*  -p ports-file: List of ports are read from ports-file. Port ranges\n     can be specified by using a hyphen, eg 10-50\n*  -i interfaces-file: List of interfaces are read from interfaces-file.\n*  -a : Listen on all PCAP supported interfaces (except USB and \"any\")\n*  -r : Enable rate limiting per source IP+destination UDP port combination\n*  -t nnn : Set rate limiter to nnn ms. Defaults to 1000ms. Implies -r\n*  -l : Turns on Stat logging (log RX/TX/DROP Packets to stats.log)\n*  -d : Turns on debug (doesn't do much yet\n*  -h : Shows this help\n\nMultiple port or interface files can be specified. \n\nExample port and interface files are given. \n\nOnly **one** instance of SDH should run on each VLAN. If more than one instance is run on the same PC, broadcasts will be retransmitted *n* times. If more than one copy is run on more than one PC, and there are shared VLANs, a broadcast loop and flood **will** happen. \n\nRate limiting can be enabled with a command line flag. It is **strongly** recommended that you enable this, unless you're 100% confident that you know what you're doing and you won't accidentally cause a loop. See below for a brief rate limting explanation. \n\n*Important information regarding a segault:* if run the application and you get crash on start, try splitting your ports file up in to multiple files and running multiple instances of SDH. This bug needs some love, but the workaround is simple .\n\n### Advanced usage\n\nIf you do not want to trunk every VLAN to one point on your network, you may\ncreate a bridging VLAN and run multiple instances of SDH. Consider the bridging\nVLAN is 100, and the user networks are VLANs 101, 102, 103 and 104. Run two\ninstances of SDH, one connected to VLANs 100, 101 and 102, and the second \ninstance connected to VLANs 100, 103 and 104. Packets broadcast on to the bridging VLAN \nwill be rebroadcast again by other instances of SDH. The bridging VLAN could also \nbe a VPN or similar. \n\n### Rate limiting\n\nRate limiting is an optional feature that can be used for mostly-effective \ndamage control in the event of a network loop, and preventing spammy\nprograms from affecting your entire network. \n\nEvery packet that is considered for retransmission has its source IP address\nand destination UDP port compared to a list of recent packets. If that same pair of \nsource IP and destination port have been retransmitted within the last timeout \nperiod, then the packet is dropped. \n\nThe use of this combination means that when, eg, the Steam server browser \nsends broadcasts on each of ports 27015 to 27020, it will not trigger the \nrate limiter. But, if there is a network loop or a very spammy program, \nthe same IP+port combination will be seen many times in a short period, \nand the rate limiter will drop all but 1 instance of the packet in every\ntimeout period. \n\nThe default timeout is 1000ms, which is more than enough to prevent a loop from \nforming if the circumstances for it to happen arise, and is small enough that \nit should not interfere with any legitimate discovery applications. \n\n### Stat collection\n\nEnable the `-l` flag to enable logging of statistics to a file. Then \n[use this script](https://gist.github.com/solariz/29362abbcf45605ab700df6f6e6be141)\nto ingest the data in to InfluxDB.\n\nThanks to Solariz from DreamHack for this feature!\n\n\n### What SDH *does* do \n\n1. Copy/retransmit ethernet frames containing UDP broadcast packets on whitelisted ports between network interfaces\n2. Optionally enforce a rate limit to prevent a network flood in the case of a loop\n\n### What SDH *does not* do\n\n1. Routing. This is not a router. Your non-UDP-broadcast IP traffic will still need a normal router to move between LAN segments. \n2. Ethernet bridging. I guess technically it could be considered an ethernet bridge, but only one that \nforwards very incredibly selectively. \n3. Intelligent retransmission decisions. A malicious user could flood your network with targetted traffic. A future feature could be a rate limiter to avoid flooding a gigabit of traffic across the network. \n4. Source verification. Neither source IP or MAC address are verified. A future feature could be to ensure that the source IP address is within the subnet of the interface it was detected on, but this would prevent multi-hop broadcasts. \n\nThe most important bit out of that is: this tool does not carry your game/application traffic. \nBroadcasts are (usually) only used for network announcement and discovery. Your game client \nwill send a discovery broadcast packet (ie, host to everyone), which SDH will retransmit. The game server will reply with a \nunicast (ie, host to host). Unicast is not broadcast, and will not be retransmitted by SDH. The unicast packets will go via the path they would have if SDH was not running. \n\n### What problems might SDH not fix?\n\nYour program might have a serious case of the bad programmer, and cannot deal with \"LAN\" clients being on different subnets.\n\n\n### What has this been used for?\n\n**PAX Aus 2016 PC area**\n\u003eWe _finally_ used this at an event - PAX Aus 2016 PC area. \n\u003e\n\u003eit seemed to work pretty well. One VLAN apparently had some trouble discovering servers, but I did not get to investigate at the time, \u003eso can't rule out individual PC problems, switch misconfiguration or bug in the application. \n\n**DREAMHACK Ger 2016 LAN area**\n\u003e We used it at DHDE17 too. 1.500 users run very well on a enabled rate limiting at -t 750.\n\u003e Tested and added several games to the ports, after adding a bunch of ports the SDH crashed on memory exhaust but could be fixed by enabling the pcap optimized compile in code.\n\n\n### To do list\n\n* Detect whether the broadcast is going to 255.255.255.255 or to the last \naddress in the subnet (eg, 10.0.0.255). If the latter, rewrite the address \nfor the new subnet. Current implementation leaves address as is. Means it\nonly works if it gets sent to 255.255.255.255. Making this change would \nrequire either detection or configuration of what IP range each interface\nused.\n* Not segfaulting if not run with libpcap capture permissions (eg, root)\n* Fix segfault when providing a large ports file\n\nIdeas for someone who might find them useful to implement:\n* Verify sender by ARP before retransmitting a frame\n* Detect loops by watching for duplicate frames from the same source (this may be problematic, as some applications generate identical frames every time)\n\n\n### License\n\nPublished under the MIT license. See LICENSE for licensing information. Please email me if you use this, I'd love to know \u003c3\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenSourceLAN%2Fservice-discovery-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOpenSourceLAN%2Fservice-discovery-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenSourceLAN%2Fservice-discovery-helper/lists"}